@communecter/cocolight-api-client 1.0.140 → 1.0.141

package/package.json

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

package/src/ApiClient.ts

@@ -1648,7 +1648,11 @@ export default class ApiClient extends EventEmitter {
     "imageThumb",
     "imageMediumPath",
     "logo",
-    "logoMin"
+    "logoMin",
+    // `image` : chemin relatif renvoyé par Document::getDocumentPath (ex: valeurs
+    // thématiques de COSTUM_FILTER_COFORM_BY_PATH). _normalizeImage ne touche que les
+    // strings non vides → "" et non-strings restent inchangés (pas d'effet de bord).
+    "image"
   ];
 
   /**

package/src/api/BaseEntity.ts

@@ -46,6 +46,7 @@ import type {
   SearchMemberAutocompleteData,
   GetEventsData,
   CostumFilterCoformData,
+  CostumFilterCoformByPathData,
   GetCountriesData,
   SearchZonesData,
   CoformAnswersByFormsData,
@@ -252,6 +253,31 @@ export type CostumContextFields = {
 
 export type WithCostumContext<T> = T & CostumContextFields;
 
+/**
+ * Une valeur distincte d'une thématique CoForm (retournée par `coformFilterByPath`).
+ */
+export interface CoformThematicValue {
+  /** Nom de la valeur de thématique (ex: "Cafés cantines solidaires"). */
+  name: string;
+  /** URL de l'image associée (chaîne vide si aucune). */
+  image: string;
+  /** Identifiants des éléments liés via le finder (orgas/projets/poi selon finderPath). */
+  orgaNameArray: string[];
+}
+
+/**
+ * Résultat normalisé de `coformFilterByPath` (endpoint COSTUM_FILTER_COFORM_BY_PATH).
+ * Reconstruit proprement la réponse backend que le normalizer générique aplatit.
+ */
+export interface CoformFilterByPathResult {
+  /** _id des answers concernées par la thématique (dédupliqués). */
+  distinctElements: string[];
+  /** Valeurs distinctes de la thématique, chacune avec image/name/éléments liés. */
+  values: CoformThematicValue[];
+  /** Compteurs renvoyés par le backend (ex: `{ answers: 14 }`). */
+  count: Record<string, number>;
+}
+
 // Type pour le curseur de pagination utilisé dans _createPaginatorEngine
 type PaginationCursor = {
   searchType?: string[];
@@ -5369,6 +5395,93 @@ export class BaseEntity<TServerData = any> {
     return wrappedFinalizer(data);
   }
 
+  /**
+   * Récupère les valeurs distinctes d'**une seule** thématique CoForm, query pilotée
+   * côté client via `params.thematicPath` (+ `params.finderPath` optionnel).
+   *
+   * Distinct de {@link coformFiltersSearch} (qui passe `searchedData` et fait le batch
+   * multi-filtres piloté serveur) : ici on cible UN filtre précis et on construit
+   * soi-même la projection (`fields`) et les `filters`. Côté backend, c'est la branche
+   * `isset($_POST["params"])` du controller AutoGlobalThematicNtwrkAction.
+   *
+   * Utile pour un **filtre par réseau régional/thématique** : on combine `params` avec
+   * `notSourceKey: true` (cherche dans tout le réseau) ou `sourceKey: ["<réseau>"]`
+   * (scope un réseau précis — cf. `_withCostumContext`).
+   *
+   * @param data - `params.thematicPath` est requis ; le reste (fields/filters/searchType/
+   *   sortBy/indexMin/indexStep/notSourceKey/locality) est optionnel.
+   * @returns {@link CoformFilterByPathResult} : `{ distinctElements, values, count }`.
+   *   Reconstruit proprement la map backend que le normalizer générique aplatit
+   *   (la clé `results` est traitée comme wrapper de liste par `_transformData`).
+   * @throws {ApiError} 400 si `params.thematicPath` est absent.
+   *
+   * @example
+   * const res = await project.coformFilterByPath({
+   *   params: {
+   *     thematicPath: "lesCommunsDesTierslieux17102023_108_0.multiCheckboxPlus...",
+   *     finderPath: "answers.lesCommunsDesTierslieux17102023_108_0.finder...",
+   *   },
+   *   fields: [
+   *     "answers.lesCommunsDesTierslieux17102023_108_0.multiCheckboxPlus...",
+   *     "answers.lesCommunsDesTierslieux17102023_108_0.finder...",
+   *   ],
+   *   filters: {
+   *     "answers.lesCommunsDesTierslieux17102023_108_0.multiCheckboxPlus...": { $exists: true },
+   *   },
+   *   searchType: ["answers"],
+   *   notSourceKey: true,
+   * });
+   * res.count.answers;            // 14
+   * res.values[0].name;          // "Cafés cantines solidaires"
+   * res.values[0].orgaNameArray; // ["5b740..."]
+   * res.distinctElements;        // string[] des _id concernés
+   */
+  async coformFilterByPath(
+    data: Partial<CostumFilterCoformByPathData> & { params: CostumFilterCoformByPathData["params"] },
+  ): Promise<CoformFilterByPathResult> {
+    if (!data?.params || typeof data.params.thematicPath !== "string" || data.params.thematicPath.trim() === "") {
+      throw new ApiError("coformFilterByPath : params.thematicPath est requis (string non vide).", 400);
+    }
+    const wrappedFinalizer = this._withCostumContext(
+      (finalData: CostumFilterCoformByPathData) => this.endpointApi.costumFilterCoformByPath(finalData)
+    );
+    const raw = await wrappedFinalizer(data) as Record<string, unknown>;
+
+    // Le normalizer (_transformData) convertit la map `results` en array où chaque
+    // entrée reçoit `id: <cléOriginale>` :
+    //  - distinctElements (array) → { id: "distinctElements", 0: "<_id>", 1: "<_id>", ... }
+    //  - chaque valeur thématique → { id: "<nom>", name, image, orgaNameArray }
+    // On reconstruit la structure propre à partir de ça.
+    const rawResults = Array.isArray(raw?.results) ? (raw.results as Array<Record<string, unknown>>) : [];
+
+    let distinctElements: string[] = [];
+    const values: CoformThematicValue[] = [];
+
+    for (const entry of rawResults) {
+      if (!entry || typeof entry !== "object") continue;
+      if (entry.id === "distinctElements") {
+        distinctElements = Object.entries(entry)
+          .filter(([k]) => /^\d+$/.test(k))
+          .sort(([a], [b]) => Number(a) - Number(b))
+          .map(([, v]) => String(v));
+        continue;
+      }
+      values.push({
+        name: typeof entry.name === "string" ? entry.name : String(entry.id ?? ""),
+        image: typeof entry.image === "string" ? entry.image : "",
+        orgaNameArray: Array.isArray(entry.orgaNameArray)
+          ? (entry.orgaNameArray as unknown[]).map((x) => String(x))
+          : [],
+      });
+    }
+
+    const count = (raw?.count && typeof raw.count === "object")
+      ? (raw.count as Record<string, number>)
+      : { answers: values.length };
+
+    return { distinctElements, values, count };
+  }
+
 
   /**
    * Recherche des zones géographiques selon un pays et un niveau administratif.

package/src/api/EndpointApi.ts

@@ -2,7 +2,7 @@
 import { ApiAuthenticationError } from "../error.js";
 
 import type ApiClient from "../ApiClient.js";
-import type { PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeletePoiData, DeleteEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, SaveCoformAnswerData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData } from "./EndpointApi.types.js";
+import type { PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeletePoiData, DeleteEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, SaveCoformAnswerData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData } from "./EndpointApi.types.js";
 
 /**
  * Classe EndpointApi générée automatiquement depuis endpoints-copie.json
@@ -1829,6 +1829,21 @@ export class EndpointApi {
     return this.call("COSTUM_FILTER_COFORM", data);
   }
 
+  /**
+   * Filtre CoForm par path (thématique unique) : Récupère les valeurs distinctes d'UNE thématique CoForm (branche `isset($_POST['params'])` du controller AutoGlobalThematicNtwrkAction). La query est construite côté client via `params.thematicPath` (+ `params.finderPath` optionnel) ; le serveur fait un seul globalAutoComplete + tri. Distinct de COSTUM_FILTER_COFORM (branche `searchedData`, multi-filtres pilotés serveur).
+   * Constant : COSTUM_FILTER_COFORM_BY_PATH
+   * @param data - Données envoyées à l'API
+   * @returns 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 costumFilterCoformByPath(data: CostumFilterCoformByPathData): Promise<any> {
+    if (!data || typeof data !== "object") {
+      throw new TypeError("Le paramètre data doit être un objet.");
+    }
+    return this.call("COSTUM_FILTER_COFORM_BY_PATH", data);
+  }
+
   /**
    * Récupérer la liste des pays : Récupérer la liste de tous les pays
    * Constant : GET_COUNTRIES

package/src/api/EndpointApi.types.ts

@@ -5733,6 +5733,109 @@ export interface CostumFilterCoformData {
 }
 
 
+export interface CostumFilterCoformByPathData {
+  /**
+   * Discriminant de la branche B : chemins de la thématique et du finder. Sa présence aiguille le controller vers le mode single-filtre client-driven.
+   */
+  params: {
+    /**
+     * Chemin de la thématique dans answers (ex: `formKey.multiCheckboxPlus...`). Devient `path` côté backend.
+     */
+    thematicPath: string;
+    /**
+     * Chemin du finder (ex: `answers.formKey.finder...`). Optionnel : défaut backend `links.organizations`.
+     */
+    finderPath?: string;
+  };
+  /**
+   * Types d'entités à inclure (typiquement `["answers"]`).
+   */
+  searchType?: string[];
+  /**
+   * Projection : champs à retourner (incluant thematicPath et finderPath).
+   */
+  fields?: string[];
+  /**
+   * Filtres MongoDB additionnels (objet) ou chaîne vide.
+   */
+  filters?:
+    | {
+        [k: string]: unknown;
+      }
+    | "";
+  /**
+   * Champ de tri (clé = champ, valeur = 1 ou -1).
+   */
+  sortBy?: {
+    [k: string]: 1 | -1;
+  };
+  /**
+   * Index de départ pour la pagination.
+   */
+  indexMin?: number;
+  /**
+   * Nombre d'éléments à récupérer (haut par défaut : agrégation des valeurs distinctes).
+   */
+  indexStep?: number;
+  /**
+   * Comptage des types dans la réponse.
+   */
+  count?: boolean;
+  /**
+   * Extension Fediverse (toujours désactivée).
+   */
+  fediverse?: boolean;
+  /**
+   * Si true, ignore le filtre sourceKey côté backend (recherche dans tout le réseau, pas seulement le costum courant).
+   */
+  notSourceKey?: boolean;
+  /**
+   * Type initial de la recherche (vide par défaut).
+   */
+  initType?: string;
+  /**
+   * Localités ciblées (object keyé, array d'objets, ou chaîne vide).
+   */
+  locality?:
+    | {
+        [k: string]: unknown;
+      }
+    | {
+        [k: string]: unknown;
+      }[]
+    | "";
+  /**
+   * ID du contexte costum (auto-injecté par _withCostumContext).
+   */
+  contextId?: string;
+  /**
+   * Type du contexte costum (auto-injecté).
+   */
+  contextType?: "projects" | "organizations";
+  /**
+   * Slug du costum (auto-injecté par _withCostumContext).
+   */
+  costumSlug?: string;
+  /**
+   * Alias historique de contextId (auto-injecté).
+   */
+  costumId?: string;
+  /**
+   * Alias historique de contextType (auto-injecté).
+   */
+  costumType?: "projects" | "organizations";
+  /**
+   * Mode édition costum (toujours désactivé).
+   */
+  costumEditMode?: boolean;
+  /**
+   * Clés de source pour filtrer (ignoré si notSourceKey=true).
+   */
+  sourceKey?: string[];
+  [k: string]: unknown;
+}
+
+
 export interface GetCountriesData {
   /**
    * Slug personnalisé