@communecter/cocolight-api-client 1.0.191 → 1.0.193

package/package.json

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

@@ -72,12 +72,15 @@ type ParentLike = BaseEntity<any> & {
  *
  * - `default`   → `/co2/search/globalautocomplete`
  * - `navigator-tl` → `/costum/navigator/gettl`
+ * - `navigator-tl-ressource` → `/costum/navigator/getsressourcetl` (annuaire de ressources tiers-lieux :
+ *   même payload que gettl, réponse = answers BRUTES + porteur résolu/address/geo + documents ;
+ *   schéma 200 permissif — cf. NAVIGATOR_GET_RESSOURCE_TL)
  * - `admin`     → `/co2/search/globalautocompleteadmin/type/{type}/id/{id}/canSee/true`
  *   (SearchNew::searchAdmin — réservé aux admins de l'entité porteuse : `fields` = projection
  *   EXACTE, `preferences` NON strippé → badge/filtre `toBeValidated`, tri serveur via `sort`.
  *   pathParams {type,id} posés automatiquement depuis l'entité appelante — cf. searchCostum.)
  */
-export type SearchCostumVariant = "default" | "navigator-tl" | "admin";
+export type SearchCostumVariant = "default" | "navigator-tl" | "navigator-tl-ressource" | "admin";
 /**
  * Types de coercion backend supportés par `UPDATE_PATH_VALUE.setType`.
  *
@@ -1893,6 +1896,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.d.ts

@@ -1,5 +1,5 @@
 import type ApiClient from "../ApiClient.js";
-import type { DocumentListData, PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, PasswordResetData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, RelaunchInvitationData, ContactSendData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GlobalAutocompleteAdminCostumData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, CreateInvitationLinkData, ConnectByRefData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, SearchEventsCostumData, ShareEventsData, InviteMembersData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, DeleteCoformAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, CostumToolsCatalogData, CostumToolUsersData, CostumCommunInfoData, CostumSaveToolEnrichmentData, CostumCommunListData, GenerateAnswerFromFormData, GenerateProjectFromAnswerData, GenerateMilestoneFromDepenseData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData, PersonValidateInvitationData, ValidateInvitationByMailData, ImportPreviewData, ExportElementsData, ImportElementsData, GeocodageData, ValidateGroupData, SetSourceData, TransferSourceCheckData, TransferSourceApplyData, TransferSourceRollbackData, TransferSourceHistoryData, ModerateData, NewsModerateData, CommentModerateData, UploadDocumentData, ZoneGetShapeData, ZoneGetZonirisData, CostumListValuesData, CostumResolvedData, DirectoryProposalData, DirectoryProposalCountData, DirectoryProposalNewCounterData } from "./EndpointApi.types.js";
+import type { DocumentListData, PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, PasswordResetData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, RelaunchInvitationData, ContactSendData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GlobalAutocompleteAdminCostumData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, CreateInvitationLinkData, ConnectByRefData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, SearchEventsCostumData, ShareEventsData, InviteMembersData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, NavigatorGetRessourceTlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, DeleteCoformAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, CostumToolsCatalogData, CostumToolUsersData, CostumCommunInfoData, CostumSaveToolEnrichmentData, CostumCommunListData, GenerateAnswerFromFormData, GenerateProjectFromAnswerData, GenerateMilestoneFromDepenseData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData, PersonValidateInvitationData, ValidateInvitationByMailData, ImportPreviewData, ExportElementsData, ImportElementsData, GeocodageData, ValidateGroupData, SetSourceData, TransferSourceCheckData, TransferSourceApplyData, TransferSourceRollbackData, TransferSourceHistoryData, ModerateData, NewsModerateData, CommentModerateData, UploadDocumentData, ZoneGetShapeData, ZoneGetZonirisData, CostumListValuesData, CostumResolvedData, DirectoryProposalData, DirectoryProposalCountData, DirectoryProposalNewCounterData } from "./EndpointApi.types.js";
 /**
  * Classe EndpointApi générée automatiquement depuis endpoints-copie.json
  */
@@ -967,6 +967,15 @@ export declare class EndpointApi {
      * @throws {Error} - En cas d'erreur inattendue.
      */
     navigatorGettl(data: NavigatorGettlData): Promise<any>;
+    /**
+     * Annuaire de ressources tiers-lieux (navigator/getsressourcetl) : Recherche globale via navigator/getsressourcetl — payload identique à NAVIGATOR_GETTL / GLOBAL_AUTOCOMPLETE_COSTUM (drop-in de SearchNew::globalAutoComplete), suivi du post-traitement serveur Navigator::getRessourceTL : tiers-lieu porteur résolu via l input `finder` (address/geo/geoPosition remontés à la racine, finder.<parentId>.img), garde `filters[address.level1]` sur ce porteur (retirée du payload avant la recherche ; sans porteur → exclu), `documents` (photos) par réponse. `answers` reste un blob BRUT keyé par étape (PAS re-keyé par formId comme gettl). `fields` doit contenir `answers` ET `form` : sans `answers` projeté aucun porteur n est résolu (et la garde address.level1 exclut alors TOUT) ; sans `form`, le serveur se rabat sur les 3 chemins finder et seul le 1er (salles) résout (BUG-L-265).
+     * Constant : NAVIGATOR_GET_RESSOURCE_TL
+     * @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.
+     */
+    navigatorGetRessourceTl(data: NavigatorGetRessourceTlData): Promise<any>;
     /**
      * Récupérer les acteurs d'événement : Récupérer les acteurs (organizers, attendees, creators, animators) d'une entité événement.
      * Constant : COSTUM_EVENT_REQUEST_ACTORS