@communecter/cocolight-api-client 1.0.190 → 1.0.192

package/package.json

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

package/types/ApiClient.d.ts

@@ -42,6 +42,23 @@ export interface ApiClientOptions {
      * un artefact périmé masque indéfiniment les champs réels. Contrepartie : plus de démarrage à froid.
      */
     costumForceLive?: boolean;
+    /**
+     * Identité costum du SITE APPELANT (l'entité qui porte le costum servi par ce front).
+     * C'est le pendant client de `Costum::init` côté legacy : posée UNE fois, elle est injectée
+     * automatiquement dans le payload de tout endpoint dont le contrat déclare `costumSlug`
+     * (cf. `setSiteCostum`). À ne pas confondre avec le scope d'une ENTITÉ (`BaseEntity.setCostumScope`),
+     * qui décrit la provenance/l'autorité d'un élément — ici on décrit QUI APPELLE, pas QUI EST VISÉ.
+     */
+    siteCostum?: SiteCostumContext | null;
+}
+/**
+ * Identité costum du site appelant. `slug` = slug de l'ENTITÉ PORTEUSE (ex. `navigatorDesTierslieux`),
+ * jamais celui du moteur (`costumize`) : c'est ce slug qui est la clé de cache costum du legacy.
+ */
+export interface SiteCostumContext {
+    slug: string;
+    costumId?: string;
+    costumType?: string;
 }
 /**
  * Structure des données pour les appels d'endpoint
@@ -102,7 +119,51 @@ export default class ApiClient extends EventEmitter {
     private _refreshToken;
     private _setUserId;
     private _mode;
-    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy, costumForceLive }: ApiClientOptions);
+    /** Contexte costum du SITE appelant, injecté sur les endpoints qui le déclarent (cf. setSiteCostum). */
+    private _siteCostum;
+    constructor({ baseURL, accessToken, refreshToken, refreshUrl, endpoints, timeout, debug, maxRetries, circuitBreakerThreshold, circuitBreakerResetTime, fromJSONValue, mode, tokenStorageStrategy, costumForceLive, siteCostum }: ApiClientOptions);
+    /**
+     * Déclare l'identité costum du SITE APPELANT — l'entité au nom de laquelle ce front agit.
+     *
+     * POURQUOI. Le legacy ne sait de quel costum vient une action que par `$_POST["costumSlug"]` :
+     * `CommunecterController::beforeAction` → `costumCacheParams()` réchauffe alors le cache costum
+     * AVANT l'action, et `Mail::getCustomMail`/`Mail::getAppName` y lisent le domaine (`costum.host`),
+     * le titre, le logo et l'expéditeur de l'e-mail, tandis que `Cron::save` y stampe `source.key`.
+     * Historiquement ce contexte venait du DOMAINE servi par le legacy lui-même ; dès lors que le
+     * domaine d'un costum pointe sur un front autonome, plus rien ne le porte — d'où cette déclaration.
+     *
+     * PORTÉE. Posée une fois (au démarrage du front), elle est injectée automatiquement dans le payload
+     * de **tout endpoint dont le contrat déclare `costumSlug`** — le contrat sert de liste blanche, donc
+     * aucun endpoint de recherche ou d'upload n'est pollué. Une valeur explicite passée par l'appelant,
+     * ou une enveloppe costum d'entité ({@link BaseEntity.setCostumScope}), restent prioritaires.
+     *
+     * NE PAS CONFONDRE avec le scope d'une ENTITÉ : celui-ci dit de quel costum PROVIENT un élément
+     * (son `source.key`, qui fait autorité pour l'ÉDITER) ; celui-là dit qui APPELLE. Pour brander un
+     * e-mail c'est l'appelant qui compte — une organisation créée sous le costum « meir » et invitée
+     * depuis le site « institutBleu » doit produire un e-mail « institutBleu ».
+     *
+     * @param slug slug de l'ENTITÉ PORTEUSE du costum (ex. `navigatorDesTierslieux`), jamais celui du
+     *             moteur (`costumize`) : c'est la clé de cache costum du legacy.
+     * @param opts `costumId`/`costumType` = `contextId`/`contextType` de l'entité porteuse (facultatifs).
+     */
+    setSiteCostum(slug: string | null, opts?: {
+        costumId?: string;
+        costumType?: string;
+    }): void;
+    /** Identité costum du site appelant, ou `null` si ce client n'agit au nom d'aucun costum. */
+    getSiteCostum(): {
+        costumSlug: string;
+        costumId?: string;
+        costumType?: string;
+    } | null;
+    /**
+     * L'endpoint porte-t-il le marqueur `costumContext: "request"` du contrat — c.-à-d. reçoit-il
+     * automatiquement l'identité costum du site (cf. {@link setSiteCostum}) ?
+     * Exposé pour qu'un front qui construit lui-même un payload (`callEndpoint` brut) sache s'il doit y
+     * poser le trio à la main, SANS avoir à deviner depuis le schéma : 65 endpoints déclarent `costumSlug`
+     * avec un sens métier, seuls les endpoints marqués sont concernés.
+     */
+    hasCostumContext(constant: string): boolean;
     /**
      * Sets the access token for the API client and updates the authorization header.
      */

package/types/api/BaseEntity.d.ts

@@ -1712,8 +1712,9 @@ export declare class BaseEntity<TServerData = any> {
      * Récupérer les événements d'une entitée : liste des événements de l'entité ou elle est "organizer" ou "attendee".
      * Constant : GET_EVENTS
      * `startDateUTC`/`endDateUTC` acceptent un `Date` ou une string ISO (un `Date` est coercé en ISO).
-     * `recurrency` est typé `false` (garde parité, comme `searchEventsCostum`) : omettre (récurrents inclus
-     * en mode calendrier) ou passer `false` (exclure) ; jamais `true` (le legacy `=== true` l'exclurait → divergence).
+     * `recurrency` (booléen) : omettre ou `true` = récurrents inclus, `false` = exclus — fiable sur les deux
+     * serveurs depuis le 2026-09-04 (parse booléen legacy + miroir Node). Mode LISTE (sans date) : mêmes
+     * paramètres optionnels `from`/`to`/`order` que `searchEventsCostum` (voir sa doc).
      * @param data - Paramètres (partiels) de recherche/pagination.
      * @returns - Les données de réponse.
      */
@@ -1892,6 +1893,54 @@ export declare class BaseEntity<TServerData = any> {
      * court-circuiter sur ce test.
      */
     hasCostumScope(): boolean;
+    /**
+     * Contexte costum de REQUÊTE de cette entité — `{costumSlug, costumId?, costumType?}` ou `undefined`.
+     * Sert à BRANDER l'action côté serveur : le legacy lit `costumSlug` dans `$_POST`
+     * (`CommunecterController::beforeAction` → `costumCacheParams()`), ce qui réchauffe le cache costum
+     * AVANT l'action et donne son domaine/titre/logo/expéditeur à l'e-mail émis.
+     *
+     * ⚠ NE LIT QUE `_adminScope`, jamais `_costumCtx` — et c'est la question centrale du sujet.
+     * Les deux ne disent pas la même chose : `_costumCtx` est la PROVENANCE de l'entité, re-dérivée de
+     * `source.key` à chaque `_setData` (donc à chaque refresh), c'est-à-dire le costum qui a CRÉÉ
+     * l'élément ; `_adminScope`, posé par `setCostumScope`, dit « j'agis délibérément au nom de CE
+     * costum » et survit aux ré-hydratations. Pour brander un e-mail c'est l'APPELANT qui compte, pas
+     * la provenance de la cible. Mesuré : 7 des 19 sites ont un porteur de provenance étrangère (l'org
+     * hôte `institutBleu` porte `source.key:"meir"`) — lire `_costumCtx` ferait partir l'e-mail branché
+     * « meir », et comme l'enveloppe l'emporte sur le défaut du client, ce serait PIRE que de ne rien
+     * poser. Sans scope explicite on ne renvoie donc rien, et `ApiClient.setSiteCostum` — le costum du
+     * SITE, la bonne réponse dans le cas nominal — s'applique.
+     *
+     * Ne lève JAMAIS et n'exige pas une identité complète (contrairement à `_requireCostumCtx`) : ses
+     * appelants (invitation, connect, follow, commentaire, news…) doivent fonctionner hors costum.
+     *
+     * @internal Public par nécessité : `User` lit le contexte de SON PARENT (`this.parent`), ce qu'un
+     * membre `protected` interdit (accès inter-instances).
+     */
+    _costumRequestContext(): {
+        costumSlug: string;
+        costumId?: string;
+        costumType?: string;
+    } | undefined;
+    /**
+     * Pose l'enveloppe costum (canal Symbol) sur un payload de requête, SI un contexte est disponible.
+     *
+     * POURQUOI, alors que `ApiClient.setSiteCostum` suffit au cas nominal (un front dédié à UN costum) :
+     * l'enveloppe permet d'AGIR AU NOM d'un costum PRÉCIS, choisi par l'appelant (`setCostumScope`), et
+     * elle est PRIORITAIRE sur le défaut du client — c'est ce qu'il faut pour un back-office multi-sites,
+     * ou pour une action déclenchée sur un élément d'un autre costum que celui du front. Sans contexte :
+     * on ne pose rien (comportement historique, non régressif — le défaut du client s'applique alors).
+     *
+     * `properties` reste vide : aucun champ DATA costum ici, seulement le CONTEXTE (cf. `symbol.ts`).
+     *
+     * @param payload Payload muté en place (le Symbol est invisible pour `Object.keys`/AJV/le wire).
+     * @param ctx     Contexte à poser ; par défaut celui de CETTE entité.
+     * @protected
+     */
+    protected _stampCostumEnvelope<T extends object>(payload: T, ctx?: {
+        costumSlug: string;
+        costumId?: string;
+        costumType?: string;
+    } | undefined): T;
     /**
      * Pose EXPLICITEMENT le scope costum de l'entité — l'API OFFICIELLE pour rattacher une entité
      * HÔTE de costum (qui n'a pas de `source.key` : c'est elle la source, la lib ne lui auto-dérive
@@ -2556,19 +2605,32 @@ export declare class BaseEntity<TServerData = any> {
      * **Deux modes** (endpoint `/co2/search/agenda`), selon que tu passes une date ou non :
      *
      * 1. **CALENDRIER** — déclenché par `startDateUTC` et/ou `endDateUTC` (l'agenda d'une période) :
-     *    ramène **TOUT** ce qui matche la plage — ponctuels **+ récurrents** (`openingHours`, sauf `recurrency:false`) —
-     *    trié par **occurrence** (`startDateSort`/`startDateSortFormat` calculés côté serveur), résultat = **tableau**.
-     *    **Pas de pagination** serveur : une seule page (`next()`/`prev()` sans effet).
-     * 2. **LISTE** — déclenché par l'**absence** de date (flux paginé) :
-     *    **ponctuels uniquement** (récurrents exclus), triés par `startDate` **décroissant** (plus récents d'abord),
-     *    paginés via `indexMin`/`indexStep` (défaut 30) — `next()`/`prev()` fonctionnent. (Backend : objet keyé `_id`,
-     *    hydraté en tableau d'`Event` côté lib.)
+     *    ramène **TOUT** ce qui matche la plage — ponctuels **+ récurrents** (`openingHours`, sauf `recurrency:false`),
+     *    chaque récurrent **déplié en une ligne par occurrence** — trié par **occurrence** (`startDateSort`/
+     *    `startDateSortFormat` calculés côté serveur), résultat = **tableau**. **Pas de pagination** serveur :
+     *    une seule page (`next()`/`prev()` sans effet). Pour une GRILLE (mois/semaine/jour).
+     * 2. **LISTE** — déclenché par l'**absence** de date (flux paginé, `indexMin`/`indexStep`, `next()`/`prev()`) :
+     *    ponctuels **+ récurrents** (depuis le legacy 14c2caa1, **une ligne par récurrent** portant sa PROCHAINE
+     *    occurrence dans `startDateSort`/`startDateSortFormat`), résultat = **tableau**. Par défaut trié par
+     *    occurrence **décroissant** et **non borné** : la 1re page contient les events les plus LOINTAINS.
+     *    Trois paramètres **optionnels** (legacy 2026-09-04, miroir Node) rendent ce mode utilisable pour
+     *    « les prochains » :
+     *    - `from` (Date ou ISO) : borne basse « pas encore terminé à from » (ponctuel : `endDate ≥ from` sinon
+     *      `startDate ≥ from` ; récurrent : prochaine occurrence calculée DEPUIS `from`, un créneau en cours reste
+     *      servi). C'est aussi l'**ancre** de la pagination : `next()` rejoue la même valeur, la clé de tri des
+     *      récurrents ne bouge pas entre deux pages — passe donc un instant figé, pas `new Date()` à chaque appel.
+     *    - `to` (Date ou ISO) : borne haute stricte sur la clé d'occurrence.
+     *    - `order` : `"asc"` | `"desc"` (défaut `"desc"`).
+     *    Dès qu'un des trois est présent, chaque ligne porte **`endDateSortFormat`** (fin d'occurrence calculée
+     *    serveur, dans le fuseau de l'événement ; `null` sans fin connue) — ne PAS la recalculer côté client.
+     *    Sans eux, la réponse est strictement celle d'avant (aucune clé nouvelle).
+     *    « Les prochains » = `{ from: now, order: "asc" }` · « Les passés » = `{ to: now, order: "desc", recurrency: false }`.
      *
      * Le scope costum (`sourceKey`) s'applique dans les **deux** modes.
      *
-     * `recurrency` est typé `false` (garde parité) : **omettre** (mode calendrier → récurrents inclus) ou passer
-     * `false` (exclure) ; **jamais `true`** — le legacy fait un test strict `=== true` qui exclurait les récurrents
-     * (divergence), valeur donc interdite au type **et** à l'AJV.
+     * `recurrency` (booléen) : omettre ou `true` = récurrents inclus, `false` = exclus (en LISTE, la requête des
+     * récurrents est sautée). Fiable sur les deux serveurs depuis le 2026-09-04 (parse booléen legacy + miroir
+     * Node) — l'ancienne garde `const:false` du contrat est levée.
      *
      * `startDateUTC`/`endDateUTC` acceptent un **`Date` ou une string ISO** : un `Date` est coercé en ISO
      * (`toISOString()`) avant l'envoi (le fil reste `type:string`). Évite le piège de l'ISO partielle
@@ -2579,9 +2641,14 @@ export declare class BaseEntity<TServerData = any> {
      * const page = await org.searchEventsCostum({ startDateUTC: debut, endDateUTC: new Date("2026-06-30T23:59:59Z") });
      * page.results.forEach((e) => console.log(e.serverData.name, e.serverData.startDateSort));
      *
-    // Mode LISTE — flux paginé (ponctuels, du plus récent)
-     * let p = await org.searchEventsCostum({ indexStep: 20 });
+    // Mode LISTE — les prochains à partir de maintenant (en cours compris), une ligne par récurrent
+     * const now = new Date(); // ancre figée, rejouée par next()
+     * let p = await org.searchEventsCostum({ indexStep: 20, from: now, order: "asc" });
+     * p.results.forEach((e) => console.log(e.serverData.startDateSortFormat, e.serverData.endDateSortFormat));
      * if (p.hasNext) p = await p.next();
+     *
+    // Mode LISTE — les passés, du plus récent, sans récurrent
+     * const passes = await org.searchEventsCostum({ indexStep: 20, to: now, order: "desc", recurrency: false });
      */
     searchEventsCostum(data?: SearchEventsCostumInput, options?: {
         restoredState?: PaginatorState;