@communecter/cocolight-api-client 1.0.54 → 1.0.56

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

@@ -1,12 +1,22 @@
 import { ApiError } from "../error.js";
-import BaseEntity from "./BaseEntity.js";
+import { BaseEntity } from "./BaseEntity.js";
 
-export class Organization extends BaseEntity {
-  static entityType = "organizations";
+import type { PaginatorPage } from "./BaseEntity.js";
+import type {
+  AddOrganizationData,
+  GetMembersAdminData,
+  GetMembersNoAdminData
+} from "./EndpointApi.types.js";
+import type { User } from "./User.js";
 
-  static entityTag = "Organization";
+type OrganizationItemNormalized = import("./serverDataType/Organization.js").OrganizationItemNormalized;
 
-  static SCHEMA_CONSTANTS = [
+export class Organization extends BaseEntity<OrganizationItemNormalized> {
+  static override entityType = "organizations";
+
+  static override entityTag = "Organization";
+
+  static override SCHEMA_CONSTANTS: string[] = [
     "ADD_ORGANIZATION",
     "UPDATE_BLOCK_DESCRIPTION",
     "UPDATE_BLOCK_INFO",
@@ -19,7 +29,7 @@ export class Organization extends BaseEntity {
   static ADD_BLOCKS = new Map([
     ["ADD_ORGANIZATION", "addOrganization"],
     ["PROFIL_IMAGE", "updateImageProfil"]
-  ]);
+  ] as const);
 
   static UPDATE_BLOCKS = new Map([
     ["UPDATE_BLOCK_DESCRIPTION", "updateDescription"],
@@ -28,39 +38,39 @@ export class Organization 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"
   ];
 
   // role = admin c'est bizarre car en faite c'est gérer dans links sur user et l'orga
   // links.members.${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
+  override transforms: Record<string, (val: any, full: any) => any> = {
+    github: (val: any, full: any) => full?.socialNetwork?.github,
+    gitlab: (val: any, full: any) => full?.socialNetwork?.gitlab,
+    facebook: (val: any, full: any) => full?.socialNetwork?.facebook,
+    twitter: (val: any, full: any) => full?.socialNetwork?.twitter,
+    instagram: (val: any, full: any) => full?.socialNetwork?.instagram,
+    diaspora: (val: any, full: any) => full?.socialNetwork?.diaspora,
+    mastodon: (val: any, full: any) => full?.socialNetwork?.mastodon,
+    telegram: (val: any, full: any) => full?.socialNetwork?.telegram,
+    signal: (val: any, full: any) => full?.socialNetwork?.signal
   };
 
-  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 Organization.ADD_BLOCKS) {
+    for (const [constant, methodName] of Array.from(Organization.ADD_BLOCKS)) {
       const blockData = this._extractChangedFieldsFromSchema(
         this.apiClient,
         constant,
@@ -68,28 +78,28 @@ export class Organization extends BaseEntity {
         () => {}
       );
       if (blockData && Object.keys(blockData).length > 0) {
-        const data = await this[methodName](blockData);
+        const data = await this._invokeBlockMethod(Organization.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 cette organisation", 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 Organization.UPDATE_BLOCKS) {
+    for (const [constant, methodName] of Array.from(Organization.UPDATE_BLOCKS)) {
       const blockData = this._extractChangedFieldsFromSchema(
         this.apiClient,
         constant,
@@ -98,59 +108,90 @@ export class Organization extends BaseEntity {
         this.removeFields
       );
       if (blockData && Object.keys(blockData).length > 0) {
-        await this[methodName](blockData);
+        await this._invokeBlockMethod(Organization.UPDATE_BLOCKS, methodName, blockData);
         hasChanged = true;
       }
     }
 
     return hasChanged;
-  }
+  };
 
-  async addOrganization(data = {}) {
+  /**
+   * Ajoute une organisation.
+   *
+   * @param data - Données de l'organisation à ajouter.
+   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité n'est pas enregistrée.
+   */
+  async addOrganization(data: AddOrganizationData): Promise<unknown> {
     return this.callIsConnected(() => this.endpointApi.addOrganization(data));
   }
 
-
-  async getOrganizations() {
-    throw new ApiError("getOrganizations n'existe pas dans Organization");
+  override async getOrganizations(): Promise<never> {
+    throw new ApiError("getOrganizations n'existe pas dans Organization", 404);
   }
 
-  async getProjects(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getProjects}
+   *
+   * Récupère les projets de l'organisation.
+   */
+  override async getProjects(data: Parameters<BaseEntity<OrganizationItemNormalized>["getProjects"]>[0] = {}) {
     return super.getProjects(data);
   }
 
-  async getEvents() {
-    throw new ApiError("getEvents pas encore implémenté dans Organization");
-  }
+  // /** @override @returns {Promise<never>} */
+  // async getEvents() {
+  //   throw new ApiError("getEvents pas encore implémenté dans Organization", 404);
+  // }
 
-  async getPois(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getPois}
+   *
+   * Récupère les points d'intérêt de l'organisation.
+   */
+  override async getPois(data: Parameters<BaseEntity<OrganizationItemNormalized>["getPois"]>[0] = {}) {
     return super.getPois(data);
   }
 
-  async getBadgesIssuer(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getBadgesIssuer}
+   *
+   * Récupère les émetteurs de badges de l'organisation.
+   */
+  override async getBadgesIssuer(data: Parameters<BaseEntity<OrganizationItemNormalized>["getBadgesIssuer"]>[0] = {}) {
     return super.getBadgesIssuer(data);
   }
 
-  async getNews(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getNews}
+   *
+   * Récupère les actualités de l'organisation.
+   */
+  override async getNews(data: Parameters<BaseEntity<OrganizationItemNormalized>["getNews"]>[0] = {}) {
     return super.getNews(data);
   }
 
-  async getSubscribers(data = {}) {
+  /**
+   * {@inheritDoc BaseEntity#getSubscribers}
+   *
+   * Récupère les abonnés de l'organisation.
+   */
+  override async getSubscribers(data: Parameters<BaseEntity<OrganizationItemNormalized>["getSubscribers"]>[0] = {}) {
     return super.getSubscribers(data);
   }
 
+
   /**
    * Récupérer les membres de l'organisation.
    * Constant : GET_MEMBERS_ADMIN / GET_MEMBERS_NO_ADMIN
-   * @param {Object} data - Les données de requête.
-   * @param {Object} options - Options supplémentaires.
-   * @param {boolean} options.toBeValidated - Indique si les membres doivent être validés.
-   * @param {boolean} options.isAdmin - Indique si l'utilisateur est admin.
-   * @param {boolean} options.isAdminPending - Indique si l'utilisateur est en attente de validation pour être 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 membres et la liste des membres.
+   * @param data - Paramètres (partiels) de recherche/pagination.
+   * @param options - Options supplémentaires.
+   * @param options.toBeValidated - Indique si les membres doivent être validés.
+   * @param options.isAdmin - Indique si l'utilisateur est admin.
+   * @param options.isAdminPending - Indique si l'utilisateur est en attente de validation pour être admin.
+   * @param options.isInviting - Indique si l'utilisateur est en attente d'invitation.
+   * @param options.roles - Liste des rôles à filtrer.
+   * @returns - Un objet contenant le nombre de membres et la liste des membres.
    * @throws {ApiResponseError} - Si une erreur se produit lors de la récupération des contributeurs.
    * 
    * @example
@@ -180,8 +221,25 @@ export class Organization extends BaseEntity {
    * 
    * 
    */
-  async getMembers(data = {}, options = {}) {
-    data.searchType = this._getDefaultFromEndpoint("GET_MEMBERS_ADMIN", "searchType");
+  async getMembers(
+    data: Partial<GetMembersAdminData | GetMembersNoAdminData> = {},
+    options: {
+      toBeValidated?: boolean;
+      isAdmin?: boolean;
+      isAdminPending?: boolean;
+      isInviting?: boolean;
+      roles?: any[];
+    } = {}
+  ): Promise<PaginatorPage<User | Organization>> {
+
+    if(!this.id) {
+      throw new ApiError("L'organisation n'est pas définie, impossible de récupérer les membres", 400);
+    }
+
+    /** « Snapshot » local, typé string */
+    const orgId = this.id as string;
+
+    data.searchType = this._getDefaultFromEndpoint("GET_MEMBERS_ADMIN", "searchType") as GetMembersAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
@@ -197,10 +255,10 @@ export class Organization extends BaseEntity {
           //   [`links.memberOf.${this.id}.toBeValidated`]: { "$exists": false },
           //   [`links.memberOf.${this.id}.isInviting`]: { "$exists": false }
           // };
-          finalData.filters = this._buildLinkFilters(this.id, { linkType: "memberOf", toBeValidated, isAdmin, isAdminPending, isInviting, roles });
+          finalData.filters = this._buildLinkFilters(orgId, { linkType: "memberOf", toBeValidated, isAdmin, isAdminPending, isInviting, roles });
         } else {
           delete finalData?.pathParams;
-          finalData.filters = this._buildLinkFilters(this.id, { linkType: "memberOf", toBeValidated: false, isAdmin, isInviting, roles });
+          finalData.filters = this._buildLinkFilters(orgId, { linkType: "memberOf", toBeValidated: false, isAdmin, isInviting, roles });
         }
   
         const fetchFn = this.isMe
@@ -211,29 +269,24 @@ export class Organization extends BaseEntity {
       }
     });
 
-    return paginator.next();
+    return paginator.next() as Promise<PaginatorPage<User | Organization>>;
   }
 
   /**
+   * {@inheritDoc BaseEntity#getGallery}
+   * 
    * Récupère la galerie de l'organisation.
-   *
-   * @param {Object} data - Les données de requête.
-   * @returns {Promise<Object>} - Un objet contenant les éléments de la galerie.
-   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
-   * @throws {Error} - En cas d'erreur inattendue.
    */
-  async getGallery(data = {}) {
+  override async getGallery(data: Parameters<BaseEntity<OrganizationItemNormalized>["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<OrganizationItemNormalized>["project"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un projet dans cette organisation", 403);
     }
@@ -241,13 +294,11 @@ export class Organization 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<OrganizationItemNormalized>["poi"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un poi dans cette organisation", 403);
     }
@@ -255,13 +306,11 @@ export class Organization 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<OrganizationItemNormalized>["event"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un event dans cette organisation", 403);
     }
@@ -269,13 +318,11 @@ export class Organization 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<OrganizationItemNormalized>["badge"]>[0] = {}) {
     if(!this.isAdmin()){
       throw new ApiError("Vous n'avez pas les droits pour créer un badge dans cette organisation", 403);
     }
@@ -283,13 +330,11 @@ export class Organization 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<OrganizationItemNormalized>["news"]>[0] = {}) {
     // TODO: qui peut créer une news sur l'organisation ?
     return super.news(newsData);
   }
@@ -303,67 +348,61 @@ export class Organization extends BaseEntity {
 
 
   /**
+   * {@inheritDoc BaseEntity#requestToJoin}
+   *
    * Envoie une demande pour rejoindre l'organisation en tant que membre.
    * L'action est soumise à validation par un administrateur de l'organisation.
-   *
-   * @returns {Promise<Object>} - Résultat de la requête d'adhésion.
-   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou si l'entité ne supporte pas l'action.
    */
-  async requestToJoin(){
+  override async requestToJoin() {
     return super.requestToJoin();
   }
 
   /**
+   * {@inheritDoc BaseEntity#requestToJoinAdmin}
+   *
    * Envoie une demande pour rejoindre l'organisation en tant qu'administrateur.
    * 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 l'entité ne supporte pas l'action.
    */
-  async requestToJoinAdmin(){
+  override async requestToJoinAdmin() {
     return super.requestToJoinAdmin();
   }
 
   /**
+   * {@inheritDoc BaseEntity#acceptInvitation}
+   *
    * Accepte une invitation à rejoindre l'organisation.
    * 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 l'entité ne supporte pas l'action.
    */
-  async acceptInvitation(){
+  override async acceptInvitation() {
     return super.acceptInvitation();
   }
 
   /**
+   * {@inheritDoc BaseEntity#leave}
+   *
    * Quitte l'organisation, que ce soit en tant que membre ou administrateur.
    * Cette action supprime le lien entre l'utilisateur et l'organisation.
-   *
-   * @returns {Promise<Object>} - Résultat de la déconnexion.
-   * @throws {ApiError} - Si l'utilisateur n'est pas connecté ou non membre.
    */
-  async leave() {
+  override async leave() {
     return super.leave();
   }
 
   /**
+   * {@inheritDoc BaseEntity#follow}
+   *
    * Suivre une organisation.
    * Cette action permet à l'utilisateur de suivre l'organisation.
-   * 
-   * @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'une organisation.
-   * 
-   * @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();
   }
 
@@ -374,23 +413,20 @@ export class Organization extends BaseEntity {
    */
 
   /**
+   * {@inheritDoc BaseEntity#getCostumJson}
+   *
    * Récupère le JSON personnalisé de l'organisation.
-   * 
-   * @returns {Promise<Object>} - Le JSON personnalisé de l'organisation.
-   * @throws {ApiError} - Si le slug de l'organisation n'est pas défini.
    */
-  async getCostumJson() {
+  override async getCostumJson() {
     return super.getCostumJson();
   }
 
   /**
-   * recherche lié à l'organisation
+   * {@inheritDoc BaseEntity#searchCostum}
    *
-   * @param {Object} data - Les données de recherche.
-   * @returns {Promise<Object>} - Résultat de la recherche.
-   * @throws {ApiError} - Si le slug ou l'id de l'organisation n'est pas défini.
+   * Cette surcharge précise que la recherche est faite dans le contexte de l'organisation.
    */
-  async searchCostum(data = {}) {
+  override async searchCostum(data: Parameters<BaseEntity<OrganizationItemNormalized>["searchCostum"]>[0]) {
     return super.searchCostum(data);
   }