@communecter/cocolight-api-client 1.0.140 → 1.0.142

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@communecter/cocolight-api-client",
-    "version": "1.0.140",
+    "version": "1.0.142",
     "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é

package/src/api/Notifications.ts

@@ -0,0 +1,196 @@
+import { batch, reactive } from "../utils/reactive.js";
+
+import type {
+  NotificationAuthor,
+  NotificationItemData
+} from "./serverDataType/Notification.js";
+
+type User = import("./User.js").User; // backref ; User porte __entityTag donc non proxifié par reactive()
+
+/** Taille de page côté serveur (ActivityStream::getNotificationsByStep indexStep=15). */
+const DEFAULT_PAGE_SIZE = 15;
+
+/** isUnread/isUnseen de CE destinataire (le serveur unset la clé quand lu/vu -> absence = faux). */
+function stateFor(data: NotificationItemData, userId: string | null, key: "isUnread" | "isUnseen"): boolean {
+  if (!userId) return false;
+  return data?.notify?.id?.[userId]?.[key] === true;
+}
+
+/**
+ * Item de notification fin. N'étend PAS BaseEntity : il garde la donnée brute, un backref
+ * User (pour router les appels via callIsMe + endpointApi) et un backref manager (pour le recount).
+ * Les drapeaux lu/vu sont réactifs (objet reactive({...}) — surface scalaire fiable).
+ */
+export class Notification {
+  private readonly _data: NotificationItemData;
+  private readonly _owner: User;
+  private _manager: Notifications | null;
+  private readonly _state: { isUnread: boolean; isUnseen: boolean };
+
+  constructor(data: NotificationItemData, owner: User, manager: Notifications | null = null) {
+    this._data = data;
+    this._owner = owner;
+    this._manager = manager;
+    const uid = owner.userId;
+    this._state = reactive({
+      isUnread: stateFor(data, uid, "isUnread"),
+      isUnseen: stateFor(data, uid, "isUnseen")
+    });
+  }
+
+  static fromData(data: NotificationItemData, owner: User, manager: Notifications | null = null): Notification {
+    return new Notification(data, owner, manager);
+  }
+
+  /** Lie l'item à son manager (appelé par le manager au wrap). */
+  _attach(manager: Notifications): this { this._manager = manager; return this; }
+
+  get id(): string { return this._data.id; }   // injecté par ApiClient._transformData (clé de la map = hex)
+  get isUnread(): boolean { return this._state.isUnread; }   // lecture réactive
+  get isUnseen(): boolean { return this._state.isUnseen; }
+  get data(): NotificationItemData { return this._data; }
+  get author(): NotificationAuthor { return this._data.author; }
+  get createdAt(): Date {
+    // ApiClient._transformData rend `created` en Date. La string ISO survient après un
+    // round-trip toJSON()->JSON.parse->restore(). On fait confiance à la normalisation amont.
+    const c = this._data.created;
+    return c instanceof Date ? c : new Date(c as string | number);
+  }
+
+  // setters locaux (utilisés par l'optimiste, sans appel réseau)
+  _setReadLocal(): void { this._state.isUnread = false; }
+  _setSeenLocal(): void { this._state.isUnseen = false; }
+  _restoreLocal(unread: boolean, unseen: boolean): void { this._state.isUnread = unread; this._state.isUnseen = unseen; }
+
+  /** Marque CET item comme lu : optimiste + rollback + recount manager. */
+  async markRead(): Promise<void> {
+    if (!this._state.isUnread) return;
+    const pu = this._state.isUnread, ps = this._state.isUnseen;
+    this._setReadLocal();
+    this._manager?._recount();
+    try {
+      await this._owner.markNotificationAsRead(this.id);
+    } catch (err) {
+      this._restoreLocal(pu, ps);
+      this._manager?._recount();
+      throw err;
+    }
+  }
+
+  /** Pas d'endpoint "seen" par item : flip local uniquement. */
+  markSeen(): void { this._setSeenLocal(); this._manager?._recount(); }
+
+  toJSON(): NotificationItemData { return this._data; }
+}
+
+/**
+ * Gestionnaire de notifications de l'utilisateur connecté. Accroché à User via `me.notifications`.
+ * N'étend PAS BaseEntity. Items dans un tableau SIMPLE (jamais proxifié) ; seuls les scalaires
+ * vivent dans un reactive({...}) (loadedUnreadCount, unseenTotal, cursor, hasMore, version).
+ * Aucun effect/computed créé ici (pas d'API de dispose -> pas de fuite).
+ */
+export class Notifications {
+  private readonly _owner: User;
+  private readonly _pageSize: number;
+  private _items: Notification[] = [];
+  private readonly _state: {
+    loadedUnreadCount: number;   // non-lus PARMI les items chargés (dérivé)
+    unseenTotal: number;         // total NON-VUS côté serveur (countNotif) — badge cloche
+    cursor: number;              // offset indexMin (nb d'items déjà chargés)
+    hasMore: boolean;
+    version: number;             // bump à chaque mutation de liste -> réactivité de `items`
+  };
+
+  constructor(owner: User, pageSize: number = DEFAULT_PAGE_SIZE) {
+    this._owner = owner;
+    this._pageSize = pageSize;
+    this._state = reactive({ loadedUnreadCount: 0, unseenTotal: 0, cursor: 0, hasMore: true, version: 0 });
+  }
+
+  // surface réactive consommateur
+  get items(): Notification[] { void this._state.version; return this._items; }
+  get loadedUnreadCount(): number { return this._state.loadedUnreadCount; }
+  get unseenTotal(): number { return this._state.unseenTotal; }   // badge "non vus"
+  get hasMore(): boolean { return this._state.hasMore; }
+
+  _recount(): void { this._state.loadedUnreadCount = this._items.filter((n) => n.isUnread).length; }
+  private _wrap(raw: NotificationItemData[]): Notification[] { return raw.map((d) => Notification.fromData(d, this._owner, this)); }
+  private _commit(items: Notification[]): void { this._items = items; this._state.version++; this._recount(); }
+
+  /** Première page (reset le curseur). Tri serveur : updated desc, 15/page. */
+  async list({ indexMin = 0 }: { indexMin?: number } = {}): Promise<Notification[]> {
+    const next = this._wrap(await this._owner.fetchNotifications({ indexMin }));
+    this._commit(next);
+    this._state.cursor = next.length;
+    this._state.hasMore = next.length >= this._pageSize;
+    return next;
+  }
+
+  /** Page suivante (curseur indexMin = nb d'items déjà chargés). Concatène par réassignation. */
+  async loadMore(): Promise<Notification[]> {
+    if (!this._state.hasMore) return [];
+    const page = this._wrap(await this._owner.fetchNotifications({ indexMin: this._state.cursor }));
+    this._commit([...this._items, ...page]);
+    this._state.cursor += page.length;
+    this._state.hasMore = page.length >= this._pageSize;
+    return page;
+  }
+
+  /** Recharge depuis le début. */
+  async refresh(): Promise<Notification[]> { this._state.cursor = 0; this._state.hasMore = true; return this.list(); }
+
+  /**
+   * Badge : total des NON-VUS via GET_NOTIFICATIONS_COUNT (refreshTimestamp = maintenant ->
+   * liste vide + countNotif). Met à jour unseenTotal et le retourne.
+   */
+  async count(): Promise<number> {
+    this._state.unseenTotal = await this._owner.fetchNotificationsCount();
+    return this._state.unseenTotal;
+  }
+
+  /**
+   * PUR : convertit des `NotificationItemData[]` plats (ex. cache React Query après
+   * hydratation SSR) en `Notification[]` liées à l'utilisateur, SANS modifier l'état du
+   * manager. À utiliser dans un `select` React Query (cache plat -> instances vivantes).
+   */
+  toItems(data: NotificationItemData[]): Notification[] {
+    return this._wrap(data);
+  }
+
+  async markAllRead(): Promise<void> { await this._bulk("read"); }
+  async markAllSeen(): Promise<void> { await this._bulk("seen"); }
+
+  private async _bulk(action: "seen" | "read"): Promise<void> {
+    const snap = this._items.map((n) => ({ n, u: n.isUnread, s: n.isUnseen }));
+    batch(() => { for (const { n } of snap) { if (action === "read") n._setReadLocal(); else n._setSeenLocal(); } });
+    if (action === "seen") this._state.unseenTotal = 0;
+    this._recount();
+    try {
+      await this._owner.markAllNotifications(action);
+    } catch (err) {
+      batch(() => { for (const { n, u, s } of snap) n._restoreLocal(u, s); });
+      this._recount();
+      throw err;
+    }
+  }
+
+  /** Supprime toutes les notifications de l'utilisateur + vide l'état local. */
+  async clear(): Promise<void> {
+    await this._owner.removeAllNotifications();
+    this._commit([]);
+    this._state.cursor = 0;
+    this._state.hasMore = false;
+    this._state.unseenTotal = 0;
+  }
+
+  // sérialisation (donnée brute ; le backref owner + l'état réactif sont re-construits au restore)
+  toJSON(): NotificationItemData[] { return this._items.map((n) => n.toJSON()); }
+  restore(rawItems: NotificationItemData[]): this {
+    this._commit(this._wrap(rawItems));
+    this._state.cursor = rawItems.length;
+    return this;
+  }
+  static restore(rawItems: NotificationItemData[], owner: User): Notifications {
+    return new Notifications(owner).restore(rawItems);
+  }
+}

package/src/api/User.ts

@@ -1,5 +1,6 @@
 import { ApiError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
+import { Notifications } from "./Notifications.js";
 import { UserMixin } from "../mixin/UserMixin.js";
 import { createSocialTransform } from "../types/transforms.js";
 
@@ -17,9 +18,14 @@ import type {
   GetOrganizationsNoAdminData,
   GetOrganizationsAdminData,
   GetFriendsAdminData,
-  DemoteAdminData
+  DemoteAdminData,
+  GetNotificationsData,
+  GetNotificationsCountData,
+  NotificationUpdateData,
+  MarkNotificationAsReadData
 } from "./EndpointApi.types.js";
 import type { Organization } from "./Organization.js";
+import type { NotificationItemData } from "./serverDataType/Notification.js";
 import type { EntityTypes } from "@/types/entities.js";
 
 type ApiClient = import("../ApiClient.js").default;
@@ -1717,6 +1723,71 @@ export class User extends BaseEntity<UserItemNormalized> {
     return retour;
   }
 
+  // ===========================================================================
+  // Notifications (sous-ressource de l'utilisateur connecté)
+  // ===========================================================================
+
+  /** Gestionnaire de notifications, créé paresseusement et mis en cache. */
+  private _notifications?: Notifications;
+
+  /**
+   * Point d'entrée `me.notifications` (composition, PAS une entité BaseEntity).
+   * Sûr : endpointApi/apiClient sont initialisés dans le constructeur avant tout accès getter.
+   */
+  get notifications(): Notifications {
+    return (this._notifications ??= new Notifications(this));
+  }
+
+  /**
+   * Récupère les notifications (mode liste). STATELESS + plat (`NotificationItemData[]`),
+   * idéal comme `queryFn` React Query / prefetch SSR — ne touche PAS le manager réactif
+   * (`me.notifications`). `ApiClient._transformData` garantit `notif` = tableau (map -> array
+   * + `id` injecté), donc on fait confiance à la normalisation amont.
+   * pathParams.id est OBLIGATOIRE : le défaut "@userId" ne matche pas le pattern de l'endpoint.
+   */
+  async fetchNotifications({ indexMin }: { indexMin?: number } = {}): Promise<NotificationItemData[]> {
+    const res = (await this.callIsMe(() => {
+      const data: GetNotificationsData = {
+        pathParams: { type: "citoyens", id: this.userId! },
+        ...(indexMin != null ? { indexMin } : {})
+      };
+      return this.endpointApi.getNotifications(data);
+    })) as { notif?: NotificationItemData[] };
+    return Array.isArray(res?.notif) ? res.notif : [];
+  }
+
+  /**
+   * Compte les notifications NON VUES (badge). STATELESS. refreshTimestamp = maintenant ->
+   * le serveur renvoie `countNotif` (total non-vus) + une liste vide.
+   */
+  async fetchNotificationsCount(): Promise<number> {
+    const res = (await this.callIsMe(() => {
+      const data: GetNotificationsCountData = {
+        pathParams: { type: "citoyens", id: this.userId! },
+        refreshTimestamp: Math.floor(Date.now() / 1000)
+      };
+      return this.endpointApi.getNotificationsCount(data);
+    })) as { countNotif?: number };
+    return typeof res?.countNotif === "number" ? res.countNotif : 0;
+  }
+
+  /** Marque une notification comme lue (MARK_NOTIFICATION_AS_READ). */
+  async markNotificationAsRead(id: string): Promise<unknown> {
+    const data: MarkNotificationAsReadData = { id };
+    return this.callIsMe(() => this.endpointApi.markNotificationAsRead(data));
+  }
+
+  /** Marque toutes les notifications comme vues/lues (NOTIFICATION_UPDATE). */
+  async markAllNotifications(action: "seen" | "read"): Promise<unknown> {
+    const data: NotificationUpdateData = { action, all: true };
+    return this.callIsMe(() => this.endpointApi.notificationUpdate(data));
+  }
+
+  /** Supprime toutes les notifications de l'utilisateur (REMOVE_ALL_NOTIFICATIONS). */
+  async removeAllNotifications(): Promise<unknown> {
+    return this.callIsMe(() => this.endpointApi.removeAllNotifications());
+  }
+
 }
 
 // Incorporation des mixins dans User

package/src/api/serverDataType/Notification.ts

@@ -0,0 +1,81 @@
+import type { DateValue, IdObject } from "./common.js";
+import type EJSONType from "../../EJSONType.js";
+
+// L'_id peut arriver sous 3 formes selon le chemin d'appel :
+//  - instance ObjectID (transform + _fromJSONValue actif — cas observé sur User.getNotifications)
+//  - { $id } (forme normalisée non-revivée)
+//  - string hex (24)
+type ObjectIDInstance = InstanceType<typeof EJSONType["ObjectID"]>;
+export type NotificationId = ObjectIDInstance | IdObject | string;
+
+/** Auteur APRÈS aplatissement par _transformData (la map oid->objet devient un objet). */
+export interface NotificationAuthor {
+  id?: string;
+  type?: string;
+  name: string;
+  profilThumbImageUrl?: string; // complété en URL absolue par la normalisation image
+  [k: string]: unknown;
+}
+
+export interface NotificationTarget {
+  type: string;
+  id: string;
+  parent?: { id: string; type: string };
+}
+
+/** État lu/vu, par destinataire. Un champ ABSENT (clé unset côté serveur) = état "faux". */
+export interface NotificationReadState {
+  isUnread?: boolean;
+  isUnseen?: boolean;
+}
+
+export interface NotificationNotify {
+  objectType?: string;
+  /** keyé par oid de destinataire -> état lu/vu de CE destinataire. */
+  id: Record<string, NotificationReadState>;
+  displayName?: string;
+  icon?: string;
+  url?: string;
+  label?: string;
+  labelArray?: Record<string, string[]>;
+  labelAuthorObject?: string;
+  repeat?: boolean;
+  [k: string]: unknown;
+}
+
+/** Un élément du tableau `notif` (forme transformée). created/updated : Date instance OU {sec,usec}. */
+export interface NotificationItemData {
+  id: string;                 // injecté depuis la clé de la map notif (= oid hex)
+  _id: NotificationId;
+  type: string;
+  verb: string;
+  author: NotificationAuthor;
+  created: Date | DateValue;
+  updated: Date | DateValue;
+  target: NotificationTarget;
+  notify: NotificationNotify;
+  timestamp?: number;         // ajouté serveur (= updated.sec)
+  timeAgo?: string;           // présent en brut, retiré au transform
+  [k: string]: unknown;
+}
+
+/**
+ * Réponse de GET_NOTIFICATIONS (mode liste, body indexMin) APRÈS transform :
+ * `notif` est un tableau (la map oid->item est convertie). Vide => [].
+ */
+export interface GetNotificationsResult {
+  notif: NotificationItemData[];
+  [k: string]: unknown;
+}
+
+/**
+ * Réponse de GET_NOTIFICATIONS_COUNT (mode badge, body refreshTimestamp non-nul) :
+ * `notif` = notifications mises à jour APRÈS le timestamp (souvent [] si timestamp = maintenant),
+ * `countNotif` = nombre TOTAL de notifications NON VUES (isUnseen) — indépendant du timestamp.
+ * countNotif n'est présent QUE si refreshTimestamp est fourni et non-nul (sinon mode liste).
+ */
+export interface GetNotificationsCountResult {
+  notif: NotificationItemData[];
+  countNotif?: number;
+  [k: string]: unknown;
+}