@communecter/cocolight-api-client 1.0.54 → 1.0.56

package/src/api/{Project.js → Project.ts}

@@ -1,12 +1,22 @@
 import { ApiError } from "../error.js";
-import BaseEntity from "./BaseEntity.js";
+import { BaseEntity } from "./BaseEntity.js";
+import { createSocialTransform, transformEntityRefs } from "../types/transforms.js";
 
-export class Project extends BaseEntity {
-  static entityType = "projects";
 
-  static entityTag = "Project";
+import type { PaginatorPage } from "./BaseEntity.js";
+import type { AddProjectData, GetContributorsAdminData, GetContributorsNoAdminData } from "./EndpointApi.types.js";
+import type { Organization } from "./Organization.js";
+import type { User } from "./User.js";
+import type { ProjectTransforms } from "../types/transforms.js";
 
-  static SCHEMA_CONSTANTS = [
+type ProjectItemNormalized = import("./serverDataType/Project.js").ProjectItemNormalized;
+
+export class Project extends BaseEntity<ProjectItemNormalized> {
+  static override entityType = "projects";
+
+  static override entityTag = "Project";
+
+  static override SCHEMA_CONSTANTS: string[] = [
     "ADD_PROJECT",
     "UPDATE_BLOCK_DESCRIPTION",
     "UPDATE_BLOCK_INFO",
@@ -19,7 +29,7 @@ export class Project extends BaseEntity {
   static ADD_BLOCKS = new Map([
     ["ADD_PROJECT", "addProject"],
     ["PROFIL_IMAGE", "updateImageProfil"]
-  ]);
+  ] as const);
 
   static UPDATE_BLOCKS = new Map([
     ["UPDATE_BLOCK_DESCRIPTION", "updateDescription"],
@@ -28,51 +38,39 @@ export class Project extends BaseEntity {
     ["UPDATE_BLOCK_INFO", "updateInfo"],
     ["UPDATE_BLOCK_SLUG", "updateSlug"],
     ["PROFIL_IMAGE", "updateImageProfil"]
-  ]);
+  ] as const);
 
-  defaultFields = {
+  override defaultFields: Record<string, any> = {
     typeElement: this.getEntityType()
   };
 
-  removeFields = [
+  override removeFields: string[] = [
     "typeElement"
   ];
 
   // links.contributors.${this.userId}.isAdmin === true
-  transforms = {
-    github: (val, full) => full?.socialNetwork?.github,
-    gitlab: (val, full) => full?.socialNetwork?.gitlab,
-    facebook: (val, full) => full?.socialNetwork?.facebook,
-    twitter: (val, full) => full?.socialNetwork?.twitter,
-    instagram: (val, full) => full?.socialNetwork?.instagram,
-    diaspora: (val, full) => full?.socialNetwork?.diaspora,
-    mastodon: (val, full) => full?.socialNetwork?.mastodon,
-    telegram: (val, full) => full?.socialNetwork?.telegram,
-    signal: (val, full) => full?.socialNetwork?.signal,
-    parent: (val) => {
-      if (!val || typeof val !== "object") return null;
-    
-      return Object.fromEntries(
-        Object.entries(val).map(([key, obj]) => [
-          key,
-          {
-            type: obj?.type ?? null,
-            name: obj?.name ?? null
-          }
-        ])
-      );
-    }
+  override transforms: ProjectTransforms = {
+    github: createSocialTransform("github"),
+    gitlab: createSocialTransform("gitlab"),
+    facebook: createSocialTransform("facebook"),
+    twitter: createSocialTransform("twitter"),
+    instagram: createSocialTransform("instagram"),
+    diaspora: createSocialTransform("diaspora"),
+    mastodon: createSocialTransform("mastodon"),
+    telegram: createSocialTransform("telegram"),
+    signal: createSocialTransform("signal"),
+    parent: transformEntityRefs
   };
 
-  async _add(payload) {
+  override _add = async (payload: Record<string, any>): Promise<void> => {
     if (!this._calledFromSave) {
-      throw new ApiError("utilisation invalide de _add, utilisez save");
+      throw new ApiError("utilisation invalide de _add, utilisez save", 400);
     }
 
     payload.id = this._newId?.();
     if (payload.slug) delete payload.slug;
 
-    for (const [constant, methodName] of Project.ADD_BLOCKS) {
+    for (const [constant, methodName] of Array.from(Project.ADD_BLOCKS)) {
       const blockData = this._extractChangedFieldsFromSchema(
         this.apiClient,
         constant,
@@ -80,28 +78,28 @@ export class Project extends BaseEntity {
         () => {}
       );
       if (blockData && Object.keys(blockData).length > 0) {
-        const data = await this[methodName](blockData);
+        const data = await this._invokeBlockMethod(Project.ADD_BLOCKS, methodName, blockData);
         if (!this.id && data?.map?.id) {
           this._draftData.id = data.map.id;
           this._draftData.slug = data.map.slug;
         }
       }
     }
-  }
+  };
 
-  async _update(payload) {
+  override _update = async (payload: Record<string, any>): Promise<boolean> => {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour modifier ce projet", 403);
     }
 
     if (!this._calledFromSave) {
-      throw new ApiError("utilisation invalide de _update, utilisez save");
+      throw new ApiError("utilisation invalide de _update, utilisez save", 400);
     }
 
     if (payload.id) delete payload.id;
     let hasChanged = false;
 
-    for (const [constant, methodName] of Project.UPDATE_BLOCKS) {
+    for (const [constant, methodName] of Array.from(Project.UPDATE_BLOCKS)) {
       const blockData = this._extractChangedFieldsFromSchema(
         this.apiClient,
         constant,
@@ -110,88 +108,132 @@ export class Project extends BaseEntity {
         this.removeFields
       );
       if (blockData && Object.keys(blockData).length > 0) {
-        await this[methodName](blockData);
+        await this._invokeBlockMethod(Project.UPDATE_BLOCKS, methodName, blockData);
         hasChanged = true;
       }
     }
 
     return hasChanged;
-  }
+  };
 
-  async addProject(data = {}) {
+  /**
+   * Ajoute un projet.
+   *
+   * @param data - Données du projet à ajouter.
+   * @returns - Résultat de l'ajout du projet.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async addProject(data: Partial<AddProjectData> = {}): Promise<unknown> {
 
     // le parent n'est pas me donc on doit ajouter le parent
-    if (!this.isMe) {
+    if (!this.isMe && this.parent) {
       data.parent = {};
       data.parent[`${this.parent.id}`] = {
         type: this.parent.getEntityType(),
-        name: this.parent.name
+        name: (this.parent as any).name
       };
     }
 
-    return this.callIsConnected(() => this.endpointApi.addProject(data));
+    return this.callIsConnected(() => this.endpointApi.addProject(data as AddProjectData));
   }
 
-  async getOrganizations() {
-    throw new ApiError(`getOrganizations n'existe pas dans ${this.constructor.name}`);
+
+  override async getOrganizations(): Promise<never> {
+    throw new ApiError(`getOrganizations n'existe pas dans ${this.constructor.name}`, 501);
   }
 
-  async getProjects(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getProjects}
+   *
+   * Récupère les projets du projet.
+   */
+  override async getProjects(data: Parameters<BaseEntity<ProjectItemNormalized>["getProjects"]>[0] = {}) {
     return super.getProjects(data);
   }
+  
 
-  async getEvents() {
-    throw new ApiError(`getEvents pas encore implémenté dans ${this.constructor.name}`);
+
+  async getEvents(): Promise<never> {
+    throw new ApiError(`getEvents pas encore implémenté dans ${this.constructor.name}`, 501);
   }
 
-  async getPois(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getPois}
+   *
+   * Récupère les points d'intérêt d'un projet.
+   */
+  override async getPois(data: Parameters<BaseEntity<ProjectItemNormalized>["getPois"]>[0] = {}) {
     return super.getPois(data);
   }
 
-  async getBadgesIssuer(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getBadgesIssuer}
+   *
+   * Récupère les émetteurs de badges d'un projet.
+   */
+  override async getBadgesIssuer(data: Parameters<BaseEntity<ProjectItemNormalized>["getBadgesIssuer"]>[0] = {}) {
     return super.getBadgesIssuer(data);
   }
 
-  async getNews(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getNews}
+   *
+   * Récupère les actualités d'un projet.
+   */
+  override async getNews(data: Parameters<BaseEntity<ProjectItemNormalized>["getNews"]>[0] = {}) {
     return super.getNews(data);
   }
 
-  async getSubscribers(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getSubscribers}
+   *
+   * Récupère les abonnés d'un projet.
+   */
+  override async getSubscribers(data: Parameters<BaseEntity<ProjectItemNormalized>["getSubscribers"]>[0] = {}) {
     return super.getSubscribers(data);
   }
 
   /**
    * Récupérer les contributeurs d'un projet.
    * Constant : GET_CONTRIBUTORS_ADMIN / GET_CONTRIBUTORS_NO_ADMIN
-   * @param {Object} data - Les données de requête.
-   * @param {Object} options - Options supplémentaires.
-   * @param {boolean} options.toBeValidated - Indique si les contributeurs doivent être validés.
-   * @param {boolean} options.isAdmin - Indique si l'utilisateur est admin.
-   * @param {boolean} options.isInviting - Indique si l'utilisateur est en attente d'invitation.
-   * @param {Array} options.roles - Liste des rôles à filtrer.
-   * @param {boolean} isNext - Indique si c'est une recherche suivante (pagination).
-   * @returns {Promise<Object>} - Un objet contenant le nombre de contributeurs et la liste des contributeurs.
+   * @param data - Paramètres (partiels) de recherche/pagination.
+   * @param options - Options supplémentaires.
+   * @param options.toBeValidated - Indique si les contributeurs doivent être validés.
+   * @param options.isAdmin - Indique si l'utilisateur est admin.
+   * @param options.isInviting - Indique si l'utilisateur est en attente d'invitation.
+   * @param options.roles - Liste des rôles à filtrer.
+   * @param isNext - Indique si c'est une recherche suivante (pagination).
+   * @returns - Un objet contenant le nombre de contributeurs et la liste des contributeurs.
    * @throws {ApiResponseError} - Si une erreur se produit lors de la récupération des contributeurs.
-   * 
+   *
    * @example
    * // Récupérer tous les contributeurs
    * const contributors = await project.getContributors();
-   * 
+   *
    * // Récupérer les contributeurs avec validation en attente
    * const contributorsToBeValidated = await project.getContributors({}, { toBeValidated: true });
-   * 
+   *
    * // Récupérer les contributeurs avec un rôle spécifique
    * const contributorsWithRole = await project.getContributors({}, { roles: ["admin"] });
-   * 
+   *
    * // Récupérer les contributeurs administrateurs
    * const adminContributors = await project.getContributors({}, { isAdmin: true });
-   * 
+   *
    * // Récupérer les contributeurs en attente d'invitation
    * const invitingContributors = await project.getContributors({}, { isInviting: true });
-   * 
+   *
    */
-  async getContributors(data = {}, options = {}) {
-    data.searchType = this._getDefaultFromEndpoint("GET_CONTRIBUTORS_ADMIN", "searchType");
+  async getContributors(
+    data: Partial<GetContributorsAdminData | GetContributorsNoAdminData> = {},
+    options: {
+      toBeValidated?: boolean;
+      isAdmin?: boolean;
+      isAdminPending?: boolean;
+      isInviting?: boolean;
+      roles?: any[];
+    } = {}
+  ): Promise<PaginatorPage<User | Organization>> {
+    data.searchType = this._getDefaultFromEndpoint("GET_CONTRIBUTORS_ADMIN", "searchType") as GetContributorsAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
@@ -222,29 +264,24 @@ export class Project extends BaseEntity {
       }
     });
 
-    return paginator.next();
+    return paginator.next() as Promise<PaginatorPage<User | Organization>>;
   }
 
   /**
+   * {@inheritDoc BaseEntity#getGallery}
+   *
    * Récupère la galerie d'un projet.
-   * 
-   * @param {Object} data - Les données de requête pour la galerie.
-   * @returns {Promise<Object>} - Un objet contenant les images de la galerie.
-   * @throws {ApiResponseError} - Si une erreur se produit lors de la récupération de la galerie.
-   * @throws {Error} - En cas d'erreur inattendue.
    */
-  async getGallery(data = {}) {
+  override async getGallery(data: Parameters<BaseEntity<ProjectItemNormalized>["getGallery"]>[0] = {}) {
     return super.getGallery(data);
   }
 
   /**
-   * Crée une instance de projet et récupère son profil si nécessaire.
+   * {@inheritDoc BaseEntity#project}
    *
-   * @param {Object} projectData - Les données nécessaires pour initialiser le projet.
-   * @returns {Promise<Project>} Une promesse qui résout l'objet Projet créé.
-   * @throws {Error} Si une erreur se produit lors de la création du projet.
+   * Crée une instance de projet et récupère son profil si nécessaire.
    */
-  async project(projectData = {}) {
+  override async project(projectData: Parameters<BaseEntity<ProjectItemNormalized>["project"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un projet dans ce projet", 403);
     }
@@ -252,13 +289,11 @@ export class Project extends BaseEntity {
   }
 
   /**
+   * {@inheritDoc BaseEntity#poi}
+   *
    * Crée une instance de POI et la récupère si nécessaire.
-   * 
-   * @param {Object} poiData - Les données nécessaires pour initialiser le POI.
-   * @returns {Promise<Poi>} Une promesse qui résout l'objet POI créé.
-   * @throws {Error} Si une erreur se produit lors de la création du POI.
    */
-  async poi(poiData = {}) {
+  override async poi(poiData: Parameters<BaseEntity<ProjectItemNormalized>["poi"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un POI dans ce projet", 403);
     }
@@ -266,13 +301,11 @@ export class Project extends BaseEntity {
   }
 
   /**
+   * {@inheritDoc BaseEntity#event}
+   *
    * Crée une instance d'événement et la récupère si nécessaire.
-   * 
-   * @param {Object} eventData - Les données nécessaires pour initialiser l'événement.
-   * @returns {Promise<Event>} Une promesse qui résout l'objet Événement créé.
-   * @throws {Error} Si une erreur se produit lors de la création de l'événement.
    */
-  async event(eventData = {}) {
+  override async event(eventData: Parameters<BaseEntity<ProjectItemNormalized>["event"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un événement dans ce projet", 403);
     }
@@ -280,13 +313,11 @@ export class Project extends BaseEntity {
   }
 
   /**
+   * {@inheritDoc BaseEntity#badge}
+   *
    * Crée une instance de badge et la récupère si nécessaire.
-   * 
-   * @param {Object} badgeData - Les données nécessaires pour initialiser le badge.
-   * @returns {Promise<Badge>} Une promesse qui résout l'objet Badge créé.
-   * @throws {Error} Si une erreur se produit lors de la création du badge.
    */
-  async badge(badgeData = {}) {
+  override async badge(badgeData: Parameters<BaseEntity<ProjectItemNormalized>["badge"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un badge dans ce projet", 403);
     }
@@ -294,13 +325,11 @@ export class Project extends BaseEntity {
   }
 
   /**
+   * {@inheritDoc BaseEntity#news}
+   *
    * Crée une instance de news et la récupère si nécessaire.
-   * 
-   * @param {Object} newsData - Les données nécessaires pour initialiser la news.
-   * @returns {Promise<News>} Une promesse qui résout l'objet News créé.
-   * @throws {Error} Si une erreur se produit lors de la création de la news.
    */
-  async news(newsData = {}) {
+  override async news(newsData: Parameters<BaseEntity<ProjectItemNormalized>["news"]>[0] = {}) {
     // TODO: qui peut créer une news sur le projet ?
     return super.news(newsData);
   }
@@ -313,67 +342,61 @@ export class Project extends BaseEntity {
    */
 
   /**
+   * {@inheritDoc BaseEntity#requestToJoin}
+   *
    * Envoie une demande pour rejoindre le projet en tant que contributeur.
    * L'action est soumise à validation par un administrateur du projet.
-   *
-   * @returns {Promise<Object>} - Résultat de la requête d'adhésion.
-   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si le projet ne supporte pas l'action.
    */
-  async requestToJoin(){
+  override async requestToJoin() {
     return super.requestToJoin();
   }
 
   /**
+   * {@inheritDoc BaseEntity#requestToJoinAdmin}
+   *
    * Envoie une demande pour devenir administrateur du projet.
    * L'action est soumise à validation par un administrateur existant.
-   *
-   * @returns {Promise<Object>} - Résultat de la requête d'administration.
-   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si le projet ne supporte pas l'action.
    */
-  async requestToJoinAdmin(){
+  override async requestToJoinAdmin() {
     return super.requestToJoinAdmin();
   }
 
   /**
+   * {@inheritDoc BaseEntity#acceptInvitation}
+   *
    * Accepte une invitation à rejoindre le projet.
    * Cette action valide un lien en attente avec l'option `isInviting`.
-   *
-   * @returns {Promise<Object>} - Résultat de la validation du lien.
-   * @throws {ApiError} - Si aucune invitation n'est en attente ou si le projet ne supporte pas l'action.
    */
-  async acceptInvitation(){
+  override async acceptInvitation() {
     return super.acceptInvitation();
   }
 
   /**
+   * {@inheritDoc BaseEntity#leave}
+   *
    * Quitte le projet, que ce soit en tant que contributeur ou administrateur.
    * Cette action supprime le lien entre l'utilisateur et le projet.
-   *
-   * @returns {Promise<Object>} - Résultat de la déconnexion.
-   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou non contributeur.
    */
-  async leave() {
+  override async leave() {
     return super.leave();
   }
 
   /**
+   * {@inheritDoc BaseEntity#follow}
+   *
    * Suivre un projet.
    * Cette action permet à l'utilisateur de suivre le projet.
-   * 
-   * @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() {
+  override async follow() {
     return super.follow();
   }
 
   /**
+   * {@inheritDoc BaseEntity#unfollow}
+   *
    * Se désabonne d'un projet.
-   * 
-   * @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() {
+  override async unfollow() {
     return super.unfollow();
   }