@communecter/cocolight-api-client 1.0.77 → 1.0.78

package/package.json

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

package/src/api/BaseEntity.ts

@@ -2231,9 +2231,8 @@ export class BaseEntity<TServerData = any> {
    * - `connectTypeConnect` : valeur envoyée pour `connect()`
    * - `connectTypeDisconnect` : valeur envoyée pour `disconnect()`
    * @throws {ApiError} - Si le type d'entité est inconnu.
-   * @protected
    */
-  protected _getLinkMeta(): LinkMeta {
+  _getLinkMeta(): LinkMeta {
     const map = {
       organizations: {
         linkType: "memberOf",

package/src/api/User.ts

@@ -888,6 +888,191 @@ export class User extends BaseEntity<UserItemNormalized> {
     }
     return super.entityBySlug(slug);
   }
+
+  /**
+   * Valide les préconditions communes pour les méthodes de vérification de rôle.
+   * @private
+   * @param methodName - Nom de la méthode appelante (pour les messages d'erreur).
+   * @param expectedTypes - Types d'entité parent autorisés.
+   * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+   * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré.
+   * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée.
+   * @throws {ApiError} 400 - Si le type d'entité parent n'est pas valide.
+   */
+  private _validateRoleCheckPreconditions(methodName: string, expectedTypes: string[]): void {
+    if (!this.userId) {
+      throw new ApiError(`Vous devez être connecté pour ${methodName}.`, 401);
+    }
+
+    if(!this.parent?.isAdmin()){
+      throw new ApiError("Vous devez être administrateur pour effectuer cette action.", 401);
+    }
+
+    if (!this.id) {
+      throw new ApiError(`${this.constructor.name} non enregistrée.`, 404);
+    }
+
+    if(!this.parent?.id){
+      throw new ApiError("L'entité parente n'est pas enregistrée.", 404);
+    }
+
+    if (!expectedTypes.includes(this.parent.getEntityType())) {
+      throw new ApiError(`L'entité doit être de type : ${expectedTypes.join(", ")}, reçu : ${this.parent.getEntityType()}`, 400);
+    }
+  }
+
+  /**
+   * Récupère le lien utilisateur pour l'entité parente.
+   * @private
+   * @returns Le lien utilisateur ou null.
+   */
+  private _getUserLinkForParent(): any {
+    const { linkType } = this.parent!._getLinkMeta();
+    const parentId = this.parent!.id;
+    if (!parentId) return null;
+    return this?.serverData?.links?.[linkType]?.[parentId] || null;
+  }
+
+  /**
+   * Vérifie si l'utilisateur est administrateur de l'entité parente.
+   *
+   * Cette méthode permet de vérifier si un utilisateur possède les droits d'administration
+   * sur l'organisation ou le projet parent. Elle est particulièrement utile après avoir
+   * récupéré des membres via `getMembers()` pour déterminer leur niveau de permissions.
+   *
+   * @returns `true` si l'utilisateur est administrateur de l'entité parente, `false` sinon.
+   *
+   * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+   * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+   * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+   * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "organizations" ou "projects".
+   *
+   * @example
+   * // Vérifier les admins d'une organisation
+   * const org = await me.organization({ slug: "openAtlas" });
+   * const members = await org.getMembers();
+   *
+   * for (const member of members.results) {
+   *   if (member.getEntityType() === "citoyens") {
+   *     if (member.isAdmin()) {
+   *       console.log(`${member.data.name} est administrateur`);
+   *     }
+   *   }
+   * }
+   *
+   * @example
+   * // Récupérer uniquement les membres admins
+   * const org = await me.organization({ slug: "myOrg" });
+   * const adminMembers = await org.getMembers({}, { isAdmin: true });
+   *
+   * // Vérifier chaque admin
+   * for (const admin of adminMembers.results) {
+   *   if (admin.getEntityType() === "citoyens" && admin.isAdmin()) {
+   *     console.log(`${admin.data.name} a les droits admin`);
+   *   }
+   * }
+   */
+  override isAdmin(): boolean {
+    this._validateRoleCheckPreconditions("isAdmin", ["organizations", "projects"]);
+    const userLink = this._getUserLinkForParent();
+    return this._validateUserLink(userLink) && userLink?.isAdmin === true && !userLink?.isAdminPending;
+  }
+
+  /**
+   * Vérifie si l'utilisateur est membre de l'organisation parente.
+   *
+   * Cette méthode permet de vérifier si un utilisateur est membre actif d'une organisation.
+   * Elle est utile pour déterminer si un utilisateur a accès aux ressources de l'organisation.
+   *
+   * @returns `true` si l'utilisateur est membre validé de l'organisation parente, `false` sinon.
+   *
+   * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+   * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+   * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+   * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "organizations".
+   *
+   * @example
+   * // Vérifier les membres d'une organisation
+   * const org = await me.organization({ slug: "myOrg" });
+   * const members = await org.getMembers();
+   *
+   * for (const member of members.results) {
+   *   if (member.getEntityType() === "citoyens" && member.isMember()) {
+   *     console.log(`${member.data.name} est membre de l'organisation`);
+   *   }
+   * }
+   */
+  override isMember(): boolean {
+    this._validateRoleCheckPreconditions("isMember", ["organizations"]);
+    const userLink = this._getUserLinkForParent();
+    return this._validateUserLink(userLink);
+  }
+
+  /**
+   * Vérifie si l'utilisateur est contributeur du projet parent.
+   *
+   * Cette méthode permet de vérifier si un utilisateur est contributeur actif d'un projet.
+   * Elle est utile pour déterminer si un utilisateur peut participer aux activités du projet.
+   *
+   * @returns `true` si l'utilisateur est contributeur validé du projet parent, `false` sinon.
+   *
+   * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+   * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+   * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+   * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "projects".
+   *
+   * @example
+   * // Vérifier les contributeurs d'un projet
+   * const project = await me.project({ slug: "myProject" });
+   * const contributors = await project.getContributors();
+   *
+   * for (const contributor of contributors.results) {
+   *   if (contributor.getEntityType() === "citoyens" && contributor.isContributor()) {
+   *     console.log(`${contributor.data.name} est contributeur du projet`);
+   *   }
+   * }
+   */
+  override isContributor(): boolean {
+    this._validateRoleCheckPreconditions("isContributor", ["projects"]);
+    const userLink = this._getUserLinkForParent();
+    return this._validateUserLink(userLink);
+  }
+
+  /**
+   * Vérifie si l'utilisateur est participant de l'événement parent.
+   *
+   * Cette méthode permet de vérifier si un utilisateur est inscrit comme participant à un événement.
+   * Elle est utile pour déterminer si un utilisateur a confirmé sa participation à l'événement.
+   *
+   * @returns `true` si l'utilisateur est participant validé de l'événement parent, `false` sinon.
+   *
+   * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+   * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+   * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+   * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+   * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "events".
+   *
+   * @example
+   * // Vérifier les participants d'un événement
+   * const event = await me.event({ slug: "myEvent" });
+   * const attendees = await event.getAttendees();
+   *
+   * for (const attendee of attendees.results) {
+   *   if (attendee.getEntityType() === "citoyens" && attendee.isAttendee()) {
+   *     console.log(`${attendee.data.name} participe à l'événement`);
+   *   }
+   * }
+   */
+  override isAttendee(): boolean {
+    this._validateRoleCheckPreconditions("isAttendee", ["events"]);
+    const userLink = this._getUserLinkForParent();
+    return this._validateUserLink(userLink);
+  }
+
 }
 
 // Incorporation des mixins dans User

package/types/api/BaseEntity.d.ts

@@ -803,9 +803,8 @@ export declare class BaseEntity<TServerData = any> {
      * - `connectTypeConnect` : valeur envoyée pour `connect()`
      * - `connectTypeDisconnect` : valeur envoyée pour `disconnect()`
      * @throws {ApiError} - Si le type d'entité est inconnu.
-     * @protected
      */
-    protected _getLinkMeta(): LinkMeta;
+    _getLinkMeta(): LinkMeta;
     /**
      * Vérifie si l'entité prend en charge les opérations de lien (`connect`, `disconnect`, etc.).
      * Utilise `_getLinkMeta()` comme source unique de vérité.

package/types/api/User.d.ts

@@ -341,5 +341,142 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      * @returns L'entité correspondante au slug.
      */
     entityBySlug(slug: string): Promise<EntityTypes>;
+    /**
+     * Valide les préconditions communes pour les méthodes de vérification de rôle.
+     * @private
+     * @param methodName - Nom de la méthode appelante (pour les messages d'erreur).
+     * @param expectedTypes - Types d'entité parent autorisés.
+     * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+     * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+     * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré.
+     * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée.
+     * @throws {ApiError} 400 - Si le type d'entité parent n'est pas valide.
+     */
+    private _validateRoleCheckPreconditions;
+    /**
+     * Récupère le lien utilisateur pour l'entité parente.
+     * @private
+     * @returns Le lien utilisateur ou null.
+     */
+    private _getUserLinkForParent;
+    /**
+     * Vérifie si l'utilisateur est administrateur de l'entité parente.
+     *
+     * Cette méthode permet de vérifier si un utilisateur possède les droits d'administration
+     * sur l'organisation ou le projet parent. Elle est particulièrement utile après avoir
+     * récupéré des membres via `getMembers()` pour déterminer leur niveau de permissions.
+     *
+     * @returns `true` si l'utilisateur est administrateur de l'entité parente, `false` sinon.
+     *
+     * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+     * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+     * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+     * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+     * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "organizations" ou "projects".
+     *
+     * @example
+     * // Vérifier les admins d'une organisation
+     * const org = await me.organization({ slug: "openAtlas" });
+     * const members = await org.getMembers();
+     *
+     * for (const member of members.results) {
+     *   if (member.getEntityType() === "citoyens") {
+     *     if (member.isAdmin()) {
+     *       console.log(`${member.data.name} est administrateur`);
+     *     }
+     *   }
+     * }
+     *
+     * @example
+     * // Récupérer uniquement les membres admins
+     * const org = await me.organization({ slug: "myOrg" });
+     * const adminMembers = await org.getMembers({}, { isAdmin: true });
+     *
+     * // Vérifier chaque admin
+     * for (const admin of adminMembers.results) {
+     *   if (admin.getEntityType() === "citoyens" && admin.isAdmin()) {
+     *     console.log(`${admin.data.name} a les droits admin`);
+     *   }
+     * }
+     */
+    isAdmin(): boolean;
+    /**
+     * Vérifie si l'utilisateur est membre de l'organisation parente.
+     *
+     * Cette méthode permet de vérifier si un utilisateur est membre actif d'une organisation.
+     * Elle est utile pour déterminer si un utilisateur a accès aux ressources de l'organisation.
+     *
+     * @returns `true` si l'utilisateur est membre validé de l'organisation parente, `false` sinon.
+     *
+     * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+     * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+     * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+     * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+     * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "organizations".
+     *
+     * @example
+     * // Vérifier les membres d'une organisation
+     * const org = await me.organization({ slug: "myOrg" });
+     * const members = await org.getMembers();
+     *
+     * for (const member of members.results) {
+     *   if (member.getEntityType() === "citoyens" && member.isMember()) {
+     *     console.log(`${member.data.name} est membre de l'organisation`);
+     *   }
+     * }
+     */
+    isMember(): boolean;
+    /**
+     * Vérifie si l'utilisateur est contributeur du projet parent.
+     *
+     * Cette méthode permet de vérifier si un utilisateur est contributeur actif d'un projet.
+     * Elle est utile pour déterminer si un utilisateur peut participer aux activités du projet.
+     *
+     * @returns `true` si l'utilisateur est contributeur validé du projet parent, `false` sinon.
+     *
+     * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+     * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+     * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+     * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+     * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "projects".
+     *
+     * @example
+     * // Vérifier les contributeurs d'un projet
+     * const project = await me.project({ slug: "myProject" });
+     * const contributors = await project.getContributors();
+     *
+     * for (const contributor of contributors.results) {
+     *   if (contributor.getEntityType() === "citoyens" && contributor.isContributor()) {
+     *     console.log(`${contributor.data.name} est contributeur du projet`);
+     *   }
+     * }
+     */
+    isContributor(): boolean;
+    /**
+     * Vérifie si l'utilisateur est participant de l'événement parent.
+     *
+     * Cette méthode permet de vérifier si un utilisateur est inscrit comme participant à un événement.
+     * Elle est utile pour déterminer si un utilisateur a confirmé sa participation à l'événement.
+     *
+     * @returns `true` si l'utilisateur est participant validé de l'événement parent, `false` sinon.
+     *
+     * @throws {ApiError} 401 - Si l'utilisateur n'est pas connecté.
+     * @throws {ApiError} 401 - Si l'utilisateur connecté n'est pas administrateur de l'entité parente.
+     * @throws {ApiError} 404 - Si l'utilisateur n'est pas enregistré (pas d'ID).
+     * @throws {ApiError} 404 - Si l'entité parente n'est pas enregistrée (pas d'ID).
+     * @throws {ApiError} 400 - Si l'entité parente n'est pas de type "events".
+     *
+     * @example
+     * // Vérifier les participants d'un événement
+     * const event = await me.event({ slug: "myEvent" });
+     * const attendees = await event.getAttendees();
+     *
+     * for (const attendee of attendees.results) {
+     *   if (attendee.getEntityType() === "citoyens" && attendee.isAttendee()) {
+     *     console.log(`${attendee.data.name} participe à l'événement`);
+     *   }
+     * }
+     */
+    isAttendee(): boolean;
 }
 export {};