@communecter/cocolight-api-client 1.0.155 → 1.0.156

package/src/api/Project.ts

@@ -1,545 +0,0 @@
-import { ApiError } from "../error.js";
-import { BaseEntity } from "./BaseEntity.js";
-import { createSocialTransform, transformEntityRefs } from "../types/transforms.js";
-
-
-import type { Action } from "./Action.js";
-import type { PaginatorPage, PaginatorState } 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";
-
-type ProjectItemNormalized = import("./serverDataType/Project.js").ProjectItemNormalized;
-
-export class Project extends BaseEntity<ProjectItemNormalized> {
-  static override entityType = "projects";
-
-  static override entityTag = "Project";
-
-  /** Bloc de création où injecter les champs costum (CostumScope). */
-  static override COSTUM_ADD_CONSTANT = "ADD_PROJECT";
-
-  static override SCHEMA_CONSTANTS: string[] = [
-    "ADD_PROJECT",
-    "UPDATE_BLOCK_DESCRIPTION",
-    "UPDATE_BLOCK_INFO",
-    "UPDATE_BLOCK_SOCIAL",
-    "UPDATE_BLOCK_LOCALITY",
-    "UPDATE_BLOCK_SLUG",
-    "PROFIL_IMAGE"
-  ];
-
-  static ADD_BLOCKS = new Map([
-    ["ADD_PROJECT", "addProject"],
-    ["PROFIL_IMAGE", "updateImageProfil"]
-  ] as const);
-
-  static UPDATE_BLOCKS = new Map([
-    ["UPDATE_BLOCK_DESCRIPTION", "updateDescription"],
-    ["UPDATE_BLOCK_SOCIAL", "updateSocial"],
-    ["UPDATE_BLOCK_LOCALITY", "updateLocality"],
-    ["UPDATE_BLOCK_INFO", "updateInfo"],
-    ["UPDATE_BLOCK_SLUG", "updateSlug"],
-    ["PROFIL_IMAGE", "updateImageProfil"]
-  ] as const);
-
-  override defaultFields: Record<string, any> = {
-    typeElement: this.getEntityType()
-  };
-
-  override removeFields: string[] = [
-    "typeElement"
-  ];
-
-  // links.contributors.${this.userId}.isAdmin === true
-  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
-  };
-
-  /**
-   * Transforme les Answer docs imbriqués dans `data.answers` (renvoyé par /costum/navigator/gettl)
-   * en instances d'entité Answer. Voir `Organization._transformServerData` pour le même pattern.
-   *
-   * @protected
-   */
-  protected override _transformServerData(data: ProjectItemNormalized): ProjectItemNormalized {
-    const rawAnswers = (data as Record<string, unknown>).answers as Record<string, unknown[]> | undefined;
-    if (rawAnswers && typeof rawAnswers === "object") {
-      const linkedAnswers: Record<string, unknown[]> = {};
-      for (const [formId, docs] of Object.entries(rawAnswers)) {
-        // Le backend renvoie tantôt un tableau `[doc, ...]`, tantôt une map indexée
-        // par id `{ answerId: doc }`. On normalise vers un tableau dans les deux cas.
-        const list = Array.isArray(docs)
-          ? docs
-          : (docs && typeof docs === "object" ? Object.values(docs) : []);
-        linkedAnswers[formId] = list.map((doc) =>
-          doc && typeof doc === "object"
-            ? this._linkEntity("answers", { ...(doc as Record<string, unknown>), collection: "answers" })
-            : doc
-        );
-      }
-      (data as Record<string, unknown>).answers = linkedAnswers;
-    }
-    return data;
-  }
-
-  override _add = async (payload: Record<string, any>): Promise<void> => {
-    if (!this._calledFromSave) {
-      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 Array.from(Project.ADD_BLOCKS)) {
-      const blockData = this._extractChangedFieldsFromSchema(
-        this.apiClient,
-        constant,
-        { ...payload, ...this.defaultFields },
-        () => {}
-      );
-      if (blockData && Object.keys(blockData).length > 0) {
-        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;
-        }
-      }
-    }
-  };
-
-  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", 400);
-    }
-
-    // Entité costum-scopée : tout l'UPDATE part en UN `element/save` (pendant de l'ADD, hooks costum). cf. BaseEntity.
-    if (this._costumCtx) return this._saveCostumViaElementSave(payload);
-
-    if (payload.id) delete payload.id;
-    let hasChanged = false;
-
-    for (const [constant, methodName] of Array.from(Project.UPDATE_BLOCKS)) {
-      const blockData = this._extractChangedFieldsFromSchema(
-        this.apiClient,
-        constant,
-        { ...payload, ...this.defaultFields },
-        () => this.initialDraftData,
-        this.removeFields
-      );
-      if (blockData && Object.keys(blockData).length > 0) {
-        await this._invokeBlockMethod(Project.UPDATE_BLOCKS, methodName, blockData);
-        hasChanged = true;
-      }
-    }
-
-    return hasChanged;
-  };
-
-  /**
-   * 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> {
-
-    // Si le parent direct n'est pas l'utilisateur connecté (ex: création via une org),
-    // on injecte le parent dans le payload. Sans ça, le default schéma `{ "@userId": ... }`
-    // pose me comme parent — ce qui est faux pour `me.org().project()`.
-    // NB: this.isMe est trompeur ici car userContext propage jusqu'au User connecté
-    // (donc isMe=true même quand le parent direct est une org).
-    // Si le caller fournit déjà `data.parent`, on respecte sa valeur (pas de merge automatique).
-    if (this.parent && this.parent.id && this.parent.id !== this.userId && !data.parent) {
-      data.parent = {};
-      data.parent[`${this.parent.id}`] = {
-        type: this.parent.getEntityType(),
-        name: (this.parent as any).name
-      };
-    }
-
-    return this.callIsConnected(() => this.endpointApi.addProject(data as AddProjectData));
-  }
-
-  /**
-   * Supprime ce projet via `DELETE_ELEMENT` (`type=projects`).
-   *
-   * **Garde** : auteur (`serverData.creator`) OU administrateur — direct
-   * (`links.projects[id].isAdmin`) ou de l'organisation parente (via
-   * `serverData.parent` × hiérarchie). cf. {@link BaseEntity#_deleteViaElement}.
-   *
-   * ⚠️ **Destructif** : supprime le projet et potentiellement ses rattachements
-   * (actions/events/membres) côté serveur. À utiliser avec précaution.
-   *
-   * Après succès : données vidées + `_isDeleted = true`.
-   *
-   * @param reason - Raison transmise au backend (audit). Défaut `"delete project"`.
-   * @throws {ApiError} 400 si le projet n'a pas d'id.
-   * @throws {ApiError} 403 si ni auteur ni admin.
-   */
-  async delete(reason: string = "delete project"): Promise<void> {
-    await this._deleteViaElement(this.getEntityType(), reason);
-  }
-
-
-  override async getOrganizations(): Promise<never> {
-    throw new ApiError(`getOrganizations n'existe pas dans ${this.constructor.name}`, 501);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#getProjects}
-   *
-   * Récupère les projets du projet.
-   */
-  override async getProjects(data: Parameters<BaseEntity<ProjectItemNormalized>["getProjects"]>[0] = {}) {
-    return super.getProjects(data);
-  }
-  
-
-  /**
-   * {@inheritDoc BaseEntity#getEvents}
-   *
-   * Récupère les événements d'un projet.
-   */
-  override async getEvents(data: Parameters<BaseEntity<ProjectItemNormalized>["getEvents"]>[0] = {}) {
-    return super.getEvents(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);
-  }
-
-  /**
-   * {@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);
-  }
-
-  /**
-   * {@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);
-  }
-
-  /**
-   * {@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 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 });
-   *
-   * // Restreindre la recherche : uniquement les citoyens
-   * const onlyCitoyens = await project.getContributors({}, { searchType: "citoyens" });
-   *
-   * // Restreindre la recherche : uniquement les organisations
-   * const onlyOrgas = await project.getContributors({}, { searchType: "organizations" });
-   */
-  async getContributors(
-    data: Partial<GetContributorsAdminData | GetContributorsNoAdminData> = {},
-    options: {
-      toBeValidated?: boolean;
-      isAdmin?: boolean;
-      isAdminPending?: boolean;
-      isInviting?: boolean;
-      roles?: any[];
-      searchType?: "all" | "citoyens" | "organizations";
-      restoredState?: PaginatorState;
-    } = {}
-  ): Promise<PaginatorPage<User | Organization>> {
-    const allTypes = this._getDefaultFromEndpoint("GET_CONTRIBUTORS_ADMIN", "searchType") as GetContributorsAdminData["searchType"];
-    if (options.searchType === "citoyens") {
-      data.searchType = ["citoyens"];
-    } else if (options.searchType === "organizations") {
-      data.searchType = allTypes.filter(t => t !== "citoyens") as GetContributorsAdminData["searchType"];
-    } else {
-      // "all" ou omis : on initialise explicitement (le paginator exige searchType avant la validation AJV)
-      data.searchType = allTypes;
-    }
-
-    const paginator = this._createPaginatorEngine({
-      initialData: data,
-      methodName: "getContributors",
-      restoredState: options?.restoredState,
-      finalizer: async (finalData) => {
-
-        const { toBeValidated, isAdmin, isInviting, isAdminPending, roles = [] } = options;
-
-        if(this.isMe){
-          finalData.pathParams = { id: this.id };
-          // NOTE : dans le schema je crois que si pas de finalData.filters alors le default ce fait avec finalData.pathParams
-          // finalData.filters = {
-          //   [`links.projects.${this.id}`]: { "$exists": true },
-          //   [`links.projects.${this.id}.toBeValidated`]: { "$exists": false },
-          //   [`links.projects.${this.id}.isInviting`]: { "$exists": false }
-          // };
-          finalData.filters = this._buildLinkFilters(this.id, { linkType: "projects", toBeValidated, isAdmin, isAdminPending, isInviting, roles });
-        } else {
-          delete finalData?.pathParams;
-          finalData.filters = this._buildLinkFilters(this.id, { linkType: "projects", toBeValidated: false, isAdmin, isInviting, roles });
-        }
-  
-        const fetchFn = this.isMe
-          ? () => this.callIsMe(() => this.endpointApi.getContributorsAdmin(finalData))
-          : () => this.endpointApi.getContributorsNoAdmin(finalData);
-
-        return fetchFn();
-      }
-    });
-
-    return paginator.next() as Promise<PaginatorPage<User | Organization>>;
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#getGallery}
-   *
-   * Récupère la galerie d'un projet.
-   */
-  override async getGallery(data: Parameters<BaseEntity<ProjectItemNormalized>["getGallery"]>[0] = {}) {
-    return super.getGallery(data);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#searchCostum}
-   *
-   * Cette surcharge précise que la recherche est faite dans le contexte du projet.
-   */
-  override async searchCostum(
-    data: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[0],
-    options?: Parameters<BaseEntity<ProjectItemNormalized>["searchCostum"]>[1]
-  ) {
-    return super.searchCostum(data, options);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#project}
-   *
-   * Crée une instance de projet et récupère son profil si nécessaire.
-   */
-  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);
-    }
-    return super.project(projectData);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#poi}
-   *
-   * Crée une instance de POI et la récupère si nécessaire.
-   */
-  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);
-    }
-    return super.poi(poiData);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#event}
-   *
-   * Crée une instance d'événement et la récupère si nécessaire.
-   */
-  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);
-    }
-    return super.event(eventData);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#badge}
-   *
-   * Crée une instance de badge et la récupère si nécessaire.
-   */
-  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);
-    }
-    return super.badge(badgeData);
-  }
-
-
-  /**
-   * {@inheritDoc BaseEntity#form}
-   *
-   * Crée une instance de Form dans le contexte de ce projet : le Form aura
-   * `this.parent = Project`, ce qui permet à `form.getAnswers()` de déléguer
-   * `coformAnswersSearch` avec le bon costumContext.
-   */
-  override async form(formData: Parameters<BaseEntity<ProjectItemNormalized>["form"]>[0] = {}) {
-    return super.form(formData);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#news}
-   *
-   * Crée une instance de news et la récupère si nécessaire.
-   */
-  override async news(newsData: Parameters<BaseEntity<ProjectItemNormalized>["news"]>[0] = {}) {
-    if(!newsData?.id && !this.isContributor()){
-      throw new ApiError("Vous n'avez pas les droits pour créer une news dans ce projet", 403);
-    }
-    return super.news(newsData);
-  }
-
-  /**
-   * Vérifie qu'un milestoneId existe dans `serverData.oceco.milestones[]`.
-   * Sert à valider une référence avant d'attacher une entité (Action) à un milestone.
-   *
-   * @param milestoneId - L'ID du milestone à chercher.
-   * @returns `true` si trouvé, `false` sinon (y compris si oceco/milestones absents).
-   */
-  hasMilestone(milestoneId: string): boolean {
-    if (typeof milestoneId !== "string" || milestoneId.length === 0) return false;
-    const milestones = (this.serverData.oceco as { milestones?: Array<{ milestoneId?: string }> } | undefined)?.milestones;
-    if (!Array.isArray(milestones)) return false;
-    return milestones.some(m => m?.milestoneId === milestoneId);
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#action}
-   *
-   * Crée une instance d'Action liée à ce projet et la récupère si nécessaire.
-   */
-  override async action(actionData: Parameters<BaseEntity<ProjectItemNormalized>["action"]>[0] = {}) {
-    if(!actionData?.id && !this.isAdmin()){
-      throw new ApiError("Vous n'avez pas les droits pour créer une action dans ce projet", 403);
-    }
-    const entity = await this.entity("actions", actionData);
-    return entity as Action;
-  }
-  
-  /**
-   * ───────────────────────────────
-   *  Lien utilisateur ↔ projet
-   *  (rejoindre, valider, quitter, devenir admin)
-   * ───────────────────────────────
-   */
-
-  /**
-   * {@inheritDoc BaseEntity#requestToJoin}
-   *
-   * Envoie une demande pour rejoindre le projet en tant que contributeur.
-   * L'action est soumise à validation par un administrateur du projet.
-   */
-  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.
-   */
-  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`.
-   */
-  override async acceptInvitation() {
-    return super.acceptInvitation();
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#requestPromoteToAdmin}
-   *
-   * Envoie une demande de promotion en tant qu'administrateur du projet.
-   * L'utilisateur doit déjà être contributeur du projet.
-   */
-  override requestPromoteToAdmin() {
-    return super.requestPromoteToAdmin();
-  }
-
-  /**
-   * {@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.
-   */
-  override async leave() {
-    return super.leave();
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#follow}
-   *
-   * Suivre un projet.
-   * Cette action permet à l'utilisateur de suivre le projet.
-   */
-  override async follow() {
-    return super.follow();
-  }
-
-  /**
-   * {@inheritDoc BaseEntity#unfollow}
-   *
-   * Se désabonne d'un projet.
-   */
-  override async unfollow() {
-    return super.unfollow();
-  }
-
-}