@communecter/cocolight-api-client 1.0.191 → 1.0.192

package/package.json

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

@@ -1893,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

package/types/api/EndpointApi.types.d.ts

@@ -45,6 +45,18 @@ export interface PersonRegisterData {
      * Indique s’il s’agit d’une invitation (facultatif)
      */
     isInvitation?: boolean;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface AuthenticateUrlData {
@@ -77,6 +89,18 @@ export interface PasswordRecoveryData {
      * Type d'email envoyé
      */
     type: "password";
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface PasswordResetData {
@@ -133,6 +157,18 @@ export interface DeleteAccountData {
      * Raison de la suppression
      */
     reason: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     pathParams?: {
         /**
          * Identifiant de l'utilisateur à supprimer
@@ -515,6 +551,18 @@ export interface MulticonnectData {
             };
         };
     };
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface RelaunchInvitationData {
@@ -522,6 +570,18 @@ export interface RelaunchInvitationData {
      * _id du compte invité à relancer
      */
     id: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface ContactSendData {
@@ -709,6 +769,18 @@ export interface AddNewsData {
         count: number;
         [k: string]: unknown;
     }[];
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface AddImageNewsData {
@@ -851,6 +923,18 @@ export interface UpdateNewsData {
         count: number;
         [k: string]: unknown;
     }[];
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface ShareNewsData {
@@ -878,6 +962,18 @@ export interface ShareNewsData {
      * Commentaire de partage
      */
     comment?: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface GetCommentsData {
@@ -945,6 +1041,18 @@ export interface AddCommentsData {
          */
         count: number;
     }[];
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface DeleteCommentsData {
@@ -2804,6 +2912,18 @@ export interface ConnectData {
      * Type de connexion
      */
     connectType: "admin" | "member" | "contributor" | "attendee" | "friend" | "connect";
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface CreateInvitationLinkData {
@@ -2827,9 +2947,33 @@ export interface CreateInvitationLinkData {
      * URL de redirection après rattachement (optionnel)
      */
     urlRedirection?: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface ConnectByRefData {
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     pathParams?: {
         /**
          * Référence publique du lien (hex ; uniqid legacy 13 ou token Node 24) — segment d URL
@@ -2860,6 +3004,18 @@ export interface DisconnectData {
      * Type de connexion
      */
     connectType: "members" | "contributors" | "attendees" | "friends" | "followers";
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface GetElementsKeyData {
@@ -3836,6 +3992,18 @@ export interface DeleteElementData {
      * Raison de la suppression
      */
     reason: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     pathParams?: {
         /**
          * Type d'élément à supprimer
@@ -3902,6 +4070,18 @@ export interface LinkValidateData {
      * Type de validation
      */
     linkOption?: "isInviting" | "isAdminInviting" | "toBeValidated" | "isAdminPending";
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface SearchMemberAutocompleteData {
@@ -4154,6 +4334,18 @@ export interface AssignBadgesData {
         narative: string;
     }[];
     scope?: "";
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface GetEventsData {
@@ -4329,6 +4521,18 @@ export interface ShareEventsData {
      * Commentaire de partage
      */
     comment?: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface InviteMembersData {
@@ -4409,6 +4613,18 @@ export interface InviteMembersData {
             };
         };
     };
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface FollowData {
@@ -4428,6 +4644,18 @@ export interface FollowData {
      * ID de l'élément parent
      */
     parentId: string;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface GetCostumJsonData {
@@ -5740,6 +5968,18 @@ export interface AddVoteData {
          */
         status: string;
     };
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface AddReportAbuseData {
@@ -5765,6 +6005,18 @@ export interface AddReportAbuseData {
          */
         comment?: string;
     };
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface UpdatePathValueData {
@@ -5860,6 +6112,18 @@ export interface DemoteAdminData {
     childType: "citoyens";
     connect: "members" | "contributors";
     isAdmin: false;
+    /**
+     * Contexte costum de l'action : slug du SITE appelant (l'entité porteuse du costum), jamais le slug du moteur (« costumize »). Injecté automatiquement par le client (ApiClient.setSiteCostum / setCostumScope). Le legacy le lit dans $_POST — CommunecterController::costumCacheParams réchauffe alors le cache costum AVANT l'action, ce qui brande l'e-mail émis (domaine des liens, titre, logo, expéditeur) et stampe source.key sur le job cron.
+     */
+    costumSlug?: string;
+    /**
+     * Contexte costum : _id de l'entité porteuse du costum (contextId). Facultatif, complète costumSlug.
+     */
+    costumId?: string;
+    /**
+     * Contexte costum : collection de l'entité porteuse (organizations | projects | events | citoyens). Facultatif, complète costumSlug.
+     */
+    costumType?: string;
     [k: string]: unknown;
 }
 export interface CostumFilterCoformData {

package/types/api/User.d.ts

@@ -473,6 +473,18 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      * @private
      */
     private _getParentLinkForUser;
+    /**
+     * Contexte costum à faire porter par les actions de LIEN sur le parent (adhésion, validation,
+     * promotion, rétrogradation) : celui du PARENT — l'organisation/le projet/l'événement qui porte
+     * le costum du site.
+     *
+     * ⚠ JAMAIS celui de CETTE fiche citoyen : le `source.key` d'un citoyen est le costum où il s'est
+     * INSCRIT, sans aucun rapport avec le site depuis lequel l'action est faite. Comme l'enveloppe
+     * l'emporte sur le défaut du client (`ApiClient.setSiteCostum`), la poser depuis le citoyen
+     * branderait l'e-mail du MAUVAIS costum — un dégât net par rapport à ne rien poser.
+     * @private
+     */
+    private _parentCostumContext;
     /**
      * Valide les préconditions et retourne le lien parent.
      *

package/types/api/UserApi.d.ts

@@ -62,11 +62,29 @@ export declare class UserApi {
     /**
      * Lance une procédure de récupération de mot de passe.
      *
+     * Le costum, s'il est fourni, ne sert QU'À BRANDER l'e-mail envoyé (domaine du lien de
+     * réinitialisation = `costum.host`, titre, logo, expéditeur) : le legacy le lit dans `$_POST`
+     * (`CommunecterController::beforeAction` → `costumCacheParams()`) AVANT l'action, et
+     * `Mail::getCustomMail`/`Mail::getAppName` y puisent l'habillage. Aligné sur `register`.
+     *
+     * ⚠ SÉCURITÉ : `PASSWORD_RECOVERY` est `auth:"none"`. Le contexte costum est donc fourni par un
+     * appelant NON AUTHENTIFIÉ — il ne doit JAMAIS élargir un droit, ni servir à sélectionner un
+     * compte : il n'habille que le message. On ne relâche AUCUN autre champ du schéma (l'enveloppe
+     * ne porte que `context`, `properties` reste vide), et le destinataire reste résolu côté serveur
+     * depuis `email` — jamais depuis le costum.
+     *
      * @param email - Adresse email de l'utilisateur.
+     * @param opts.costumSlug - (option) slug de l'ENTITÉ PORTEUSE du costum (jamais « costumize »).
+     * @param opts.costumId / opts.costumType - (option) identité de l'entité porteuse, requises si le
+     *   slug n'est pas un doc `costum` (ex. un site porté par une organisation).
      * @returns Réponse brute de l'API.
      * @throws {ApiResponseError} Si l'API retourne un échec (`result === false`).
      */
-    recoverPassword(email: string): Promise<any>;
+    recoverPassword(email: string, { costumSlug, costumId, costumType }?: {
+        costumSlug?: string;
+        costumId?: string;
+        costumType?: string;
+    }): Promise<any>;
     /**
      * Active (valide l'email) un compte via le lien reçu par email.
      *