@communecter/cocolight-api-client 1.0.163 → 1.0.167

package/package.json

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

package/types/api/BaseEntity.d.ts

@@ -708,6 +708,48 @@ export declare class BaseEntity<TServerData = any> {
      * await news.deleteFile(imageDocId);
      */
     deleteFile(docId: string): Promise<void>;
+    /**
+     * Champs de contexte costum à joindre à un upload multipart (profil/bannière/galerie) pour que le
+     * backend stampe `source.key` (Document.php:228-232). Dérivés de `_costumCtx` (résolu du `source.key`
+     * de l'élément) → un POI scopé "parent62" envoie `costumSlug="parent62"`. `{}` hors contexte costum.
+     */
+    protected _costumUploadFields(): {
+        costumSlug?: string;
+        costumId?: string;
+        costumType?: string;
+    };
+    /**
+     * Uploade un document (image/fichier) rattaché à CET élément, avec `contentKey`/`docType`
+     * PARAMÉTRABLES — ex. `contentKey:"slider"` pour une galerie (Option C). La provenance costum
+     * (`source.key`) est injectée automatiquement depuis `_costumCtx` (résolu du `source.key` de
+     * l'élément). L'élément DOIT préexister (pas d'auto-création, contraste avec `Answer.uploadFile`).
+     * Endpoint générique `UPLOAD_DOCUMENT` (backend `co2/document/upload-save`, route wildcard).
+     *
+     * STATELESS : ne rafraîchit PAS `serverData` (pas de push local façon `News.addImage`). Pour refléter
+     * la nouvelle image dans `getGalleryImages()`, re-fetch l'élément via `about` après upload (le
+     * consommateur peut afficher optimistement via le `docPath` retourné en attendant). Cf. patron
+     * `Answer.processUploads` : la galerie s'uploade APRÈS `save()` (l'élément doit avoir un `id`).
+     *
+     * @returns `{ docId, docPath }` — id du document créé + URL relative servie.
+     * @throws {ApiError} 404 si l'entité n'est pas enregistrée (pas d'`id`).
+     */
+    uploadDocument(file: UploadInput, opts: {
+        contentKey: string;
+        docType?: "image" | "file";
+        subKey?: string;
+        folder?: string;
+        ownerId?: string;
+    }): Promise<{
+        docId: string;
+        docPath: string;
+    }>;
+    /**
+     * Images d'une galerie de CET élément, lues depuis le champ `images` fusionné par `about`/getById
+     * (backend `enrichAbout` — {Poi,Classified}::getById), filtrées par `contentKey` (défaut `"slider"`).
+     * SYNCHRONE : nécessite que l'entité ait été chargée via `about` (sinon `[]`). Forme = getListOfImage
+     * (`{ id, _id, contentKey, imagePath, imageThumbPath, imageMediumPath, subKey, name, ... }`).
+     */
+    getGalleryImages(contentKey?: string): Array<Record<string, unknown>>;
     /**
      * Liste les documents (images/fichiers) attachés à CETTE entité (`id` + `type`) via `DOCUMENT_LIST`
      * (port legacy `document/list`). Renvoie un tableau plat `{ id, name, path, author, contentKey }`.
@@ -721,6 +763,26 @@ export declare class BaseEntity<TServerData = any> {
         author?: string;
         contentKey?: string;
     }>>;
+    /**
+     * Liste les FICHIERS (documents non-image, `doctype:"file"`) attachés à CETTE entité via `GET_GALLERY`
+     * (`co2/gallery/index`, branche fichier : `docs` = OBJET keyé par `_id`, records BRUTS + `docPath`
+     * absolutisé par `_imageFields`). Source UNIQUE et uniforme tous types (org/projet/citoyen/poi/events/
+     * classifieds — l'`IndexAction` legacy est type-agnostique). Contraste `getGalleryImages` (images,
+     * synchrone via `about`) et `getDocuments` (DOCUMENT_LIST, forme réduite sans `size`/`docType`, `path`
+     * = dossier seul). Les fichiers rangés en dossier (`folderId`) sont exclus par défaut (parité
+     * `IndexAction` : `folderId:{$exists:false}`).
+     *
+     * @returns `{ docId, docPath, name, size, contentKey }[]` — `contentKey` = valeur DÉRIVÉE stockée
+     *   (`pdf`/`spreadsheet`/`text`/`presentation`), utilisable pour choisir l'icône.
+     * @throws {ApiError} 404 si l'entité n'est pas enregistrée.
+     */
+    getGalleryFiles(): Promise<Array<{
+        docId: string;
+        docPath?: string;
+        name?: string;
+        size?: number;
+        contentKey?: string;
+    }>>;
     /**
      * Supprime l'image de PROFIL de cette entité : récupère le `docId` du document `contentKey:"profil"`
      * (via `getDocuments`) puis `deleteFile`. No-op (`false`) s'il n'y a pas d'image. Pendant exact de
@@ -742,6 +804,20 @@ export declare class BaseEntity<TServerData = any> {
      * @protected
      */
     protected _markDeletedLocally(): void;
+    /** Droit d'ADMIN DE COSTUM pré-résolu par l'appelant (ex. site-json /admin via `me.isCostumAdmin(slug)`). */
+    protected _costumAdminAuthorized: boolean;
+    /**
+     * Marque cette instance comme éditable/supprimable au titre du droit-parapluie COSTUM. À poser par
+     * l'appelant qui a DÉJÀ résolu `me.isCostumAdmin(slug)` (async) — les gardes client d'édition (`_update`)
+     * et de suppression (`_deleteViaElement`) le respectent alors. Le backend reste la source de vérité
+     * (canEditItem/canDeleteElement portent isCostumAdmin), ceci n'ouvre QUE le pré-check client.
+     */
+    setCostumAdminAuthorized(v?: boolean): this;
+    /**
+     * Droit de gestion « élevé » côté client : super-admin (via userContext) OU admin de costum pré-résolu.
+     * Utilisé par les gardes `_update`/`_deleteViaElement` pour ne pas bloquer une action que le backend autorise.
+     */
+    protected _hasElevatedManageRight(): boolean;
     /**
      * Suppression générique d'un élément via `DELETE_ELEMENT`
      * (`/co2/element/delete/type/{type}/id/{id}`).
@@ -1746,12 +1822,12 @@ export declare class BaseEntity<TServerData = any> {
      * donc aucun `_costumCtx`) aux méthodes qui l'exigent (`_requireCostumCtx` : `previewImport`,
      * `importElements`, `exportElements`, `addReference`…).
      *
-     * Résolution :
-     *  1. le REGISTRE bundlé d'abord (`resolveCostumCtxFromSource` — costum connu : identité + overlay
-     *     de champs, source de vérité interne) ;
-     *  2. sinon un contexte NU construit depuis `opts` (costum de config/déploiement hors registre) —
-     *     même forme que le fallback interne (schema vide, fields:[]) ;
-     *  3. sinon throw (identité costum introuvable).
+     * Résolution (`resolveCostumCtxFromSource`, LIVE-FIRST) :
+     *  1. cache costum LIVE frais (via un `prefetchCostums`/`loadCostumScope` préalable) — champs inclus ;
+     *  2. sinon le REGISTRE bundlé (warm-start) ;
+     *  3. sinon un contexte NU construit depuis `opts` (costum hors cache/registre — schema vide, fields:[]) ;
+     *  4. sinon throw (identité costum introuvable). NB : pour un costum hors registre AVEC ses champs,
+     *     préférer `loadCostumScope(slug)` (async) qui fetche `getcostumjson`.
      *
      * Remplace la mutation externe de `_costumCtx` pratiquée par les fronts (champ INTERNE non
      * contractuel) — cf. site-json `ensureCostumScope`, à migrer sur cette méthode.
@@ -1764,6 +1840,14 @@ export declare class BaseEntity<TServerData = any> {
         costumId?: string;
         costumType?: string;
     }): void;
+    /**
+     * Charge EN LIVE (via `getcostumjson`) le scope costum d'un slug HORS registre bundlé et pose le
+     * contexte COMPLET (champs/presets/hidden) sur cette entité — pour l'ÉDITER avec ses champs costum
+     * sans re-publier la lib (RFC fil C / option 3bis, comble l'édition vide). Contrairement à
+     * `setCostumScope` (sync, registre/ctx nu), digère le typeObj du costum. No-op si le costum ne
+     * couvre pas la collection de l'entité. Idempotent (cache session par slug).
+     */
+    loadCostumScope(slug: string): Promise<boolean>;
     /**
      * Contexte costum de CETTE entité (résolu de son `source.key`) — requis par l'import/export admin.
      * @throws {ApiError} si l'entité n'est pas rattachée à un costum.

package/types/api/EndpointApi.d.ts

@@ -1,5 +1,5 @@
 import type ApiClient from "../ApiClient.js";
-import type { DocumentListData, 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, GlobalAutocompleteAdminCostumData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, 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, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData, ImportPreviewData, ExportElementsData, ImportElementsData, GeocodageData, ValidateGroupData, SetSourceData, ModerateData, NewsModerateData, CommentModerateData } from "./EndpointApi.types.js";
+import type { DocumentListData, 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, GlobalAutocompleteAdminCostumData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, 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, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData, ImportPreviewData, ExportElementsData, ImportElementsData, GeocodageData, ValidateGroupData, SetSourceData, ModerateData, NewsModerateData, CommentModerateData, UploadDocumentData } from "./EndpointApi.types.js";
 /**
  * Classe EndpointApi générée automatiquement depuis endpoints-copie.json
  */
@@ -1502,5 +1502,15 @@ export declare class EndpointApi {
      * @throws {Error} - En cas d'erreur inattendue.
      */
     commentModerate(data: CommentModerateData): Promise<any>;
+    /**
+     * Uploader un document/image sur un élément (galerie) : Uploade un document (image/fichier) rattaché à un ÉLÉMENT, avec docType/contentKey PARAMÉTRABLES (ex. contentKey=slider pour une galerie) et provenance costum optionnelle (costumSlug/costumId/costumType stampent source.key). Backend: co2/document/upload-save (route wildcard, parseKv). L'élément doit préexister.
+     * Constant : UPLOAD_DOCUMENT
+     * @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 {ApiAuthenticationError} - En cas d'erreur d'authentification.
+     * @throws {Error} - En cas d'erreur inattendue.
+     */
+    uploadDocument(data: UploadDocumentData): Promise<any>;
 }
 export default EndpointApi;

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

@@ -364,6 +364,18 @@ export interface ProfilImageData {
     profil_avatar: {
         [k: string]: unknown;
     };
+    /**
+     * Slug du costum actif (stampe source.key côté backend) — optionnel
+     */
+    costumSlug?: string;
+    /**
+     * ID du contexte costum — optionnel
+     */
+    costumId?: string;
+    /**
+     * Type (collection) du contexte costum — optionnel
+     */
+    costumType?: string;
     pathParams?: {
         /**
          * Type d'entité
@@ -391,6 +403,18 @@ export interface ProfilBannerData {
     cropH: number;
     cropX: number;
     cropY: number;
+    /**
+     * Slug du costum actif (stampe source.key côté backend) — optionnel
+     */
+    costumSlug?: string;
+    /**
+     * ID du contexte costum — optionnel
+     */
+    costumId?: string;
+    /**
+     * Type (collection) du contexte costum — optionnel
+     */
+    costumType?: string;
     pathParams?: {
         /**
          * Type d'entité
@@ -4912,9 +4936,9 @@ export interface GetGalleryData {
          */
         id: string;
         /**
-         * Type d'entité
+         * Type d'entité (IndexAction legacy est type-agnostique ; poi/events/classifieds ajoutés pour la lecture des documents/fichiers via getGalleryFiles)
          */
-        type: "citoyens" | "organizations" | "projects";
+        type: "citoyens" | "organizations" | "projects" | "poi" | "events" | "classifieds";
         /**
          * Type de document
          */
@@ -6348,3 +6372,51 @@ export interface CommentModerateData {
     isAnAbuse?: "true" | "false";
     [k: string]: unknown;
 }
+export interface UploadDocumentData {
+    /**
+     * Fichier à uploader
+     */
+    qqfile: {
+        [k: string]: unknown;
+    };
+    /**
+     * Slug du costum actif (stampe source.key=costumSlug)
+     */
+    costumSlug?: string;
+    /**
+     * ID du contexte costum
+     */
+    costumId?: string;
+    /**
+     * Type (collection) du contexte costum
+     */
+    costumType?: string;
+    /**
+     * Sous-clé de galerie (optionnelle)
+     */
+    subKey?: string;
+    /**
+     * Dossier d'album cible (optionnel)
+     */
+    folderId?: string;
+    pathParams?: {
+        /**
+         * Type (collection) de l'élément porteur
+         */
+        folder: "citoyens" | "projects" | "organizations" | "events" | "poi" | "classifieds";
+        /**
+         * ID de l'élément porteur (doit exister)
+         */
+        ownerId: string;
+        /**
+         * Nature du document
+         */
+        docType: "image" | "file";
+        /**
+         * Clé de contenu (ex: 'slider' pour galerie, 'file', 'profil', 'banner'...)
+         */
+        contentKey: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}

package/types/api/User.d.ts

@@ -70,15 +70,26 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      */
     isSuperAdmin(): boolean;
     /**
-     * Admin de plateforme (`roles.adminPlatform === true`). NB : rôle hors-legacy (absent du PHP) mais
-     * HONORÉ par le backend comme super-admin (cf. isUserSuperAdmin/deleteElement) ; posé en base, pas par le code.
+     * Admin de plateforme (`roles.adminPlatform === true`). Rôle hors-legacy (absent du PHP), posé en base.
+     * NB : le backend NE le traite PLUS comme super-admin (retiré de `isUserSuperAdmin` pour byte-fidélité) —
+     * ne l'utiliser que pour des features plateforme dédiées, pas pour gater une action que le backend refusera.
      */
     isAdminPlatform(): boolean;
     /**
-     * Accès admin plateforme large : `superAdmin || adminPlatform` (= `isUserSuperAdmin` backend général,
-     * celui de la suppression). Pour gater l'UI ; l'export reste sur `isSuperAdmin()` strict.
+     * Accès admin plateforme large : `superAdmin || adminPlatform`. Pour gater l'UI d'outils plateforme.
+     * ⚠ Le backend n'accorde l'édition/suppression qu'au `superAdmin` strict (+ droits costum) — un
+     * `adminPlatform` pur verra l'UI mais sera refusé au save/delete.
      */
     canPlatformAdmin(): boolean;
+    /**
+     * L'utilisateur connecté est-il ADMIN DU COSTUM `slug` (droit-parapluie back-office) ? = admin (lien
+     * `isAdmin` validé) de l'élément HÔTE du costum. Pendant client de `Authorisation::isCostumAdmin` :
+     * résout le host via `getElementsKey` (slug → contextId/contextType) puis lit
+     * `me.links.<memberOf|projects|events>[hostId].isAdmin`.
+     * ⚠ ASYNC (1 requête) : à résoudre UNE fois par contexte /admin, PAS par ligne de liste.
+     * NB : ne couvre pas le fallback `costum.admins` (rare) — seul le chemin admin-du-host est vérifié client-side.
+     */
+    isCostumAdmin(slug: string): Promise<boolean>;
     /**
        * Récupère le profil complet de l'utilisateur.
        * Si l'utilisateur est connecté, on appelle le endpoint ME_INFO_URL,

package/types/costum/liveDigest.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Digestion RUNTIME d'un costum servi par `getcostumjson` (format legacy brut) en
+ * `CostumRuntimeContext` par collection — permet de résoudre un costum HORS du registre bundlé sans
+ * re-publication (RFC doc/31 fil C, option 3bis). Port fidèle de `tools/parity/scripts/costum-fields.mjs`
+ * (backend), SANS l'inférence de type par valeurs stockées (pas d'accès base côté client ; en pratique
+ * inutile — `setType` BSON natif ne concerne aucun costum déployé). Le type reste DÉCLARÉ (inputType/
+ * rules), l'enum vient de `lists`, la multiplicité de la config.
+ */
+import type { CostumRuntimeContext } from "./runtime.js";
+import type { Collection } from "./types.js";
+/** Sous-objet `costum` renvoyé par `getcostumjson` (data). Champs utiles à la digestion. */
+export interface CostumJsonData {
+    slug?: string;
+    typeObj?: Record<string, TypeObjNode>;
+    lists?: Record<string, unknown>;
+}
+interface TypeObjNode {
+    sameAs?: string;
+    add?: boolean;
+    createLabel?: string;
+    dynFormCostum?: {
+        beforeBuild?: {
+            properties?: Record<string, FieldDef>;
+        };
+        onload?: {
+            actions?: OnloadActions;
+        };
+        onLoads?: {
+            onload?: {
+                actions?: OnloadActions;
+            };
+        };
+    };
+}
+interface OnloadActions {
+    presetValue?: Record<string, unknown>;
+    hide?: Record<string, unknown>;
+}
+interface FieldDef {
+    inputType?: string;
+    label?: string;
+    multiple?: boolean;
+    select2?: {
+        multiple?: boolean;
+    };
+    maximumSelectionLength?: number | string;
+    rules?: {
+        number?: unknown;
+    };
+    list?: string;
+    tagsList?: string;
+    savePath?: string;
+}
+/**
+ * Digère `getcostumjson` → `CostumRuntimeContext` pour UNE collection (null si le costum ne couvre pas
+ * cette collection). `meta` = identité de l'élément porteur (costumId/costumType, résolue par slug/getinfo).
+ */
+/** Contexte digéré + capacités de création (add/createLabel) + clé `typeObj` (sous-type) du node. */
+export type DigestedCostum = CostumRuntimeContext & {
+    add: boolean;
+    createLabel: string | null;
+    typeKey: string;
+};
+/**
+ * Énumère les FORMULAIRES d'un costum (une entrée par clé `typeObj` portant un `dynFormCostum`) — permet à
+ * l'assistant de générer un CostumFormSchema PAR SOUS-TYPE (ex. poi → `recoveryCenter` ET `article`), là où
+ * `digestCostumJson(collection)` n'en renvoie qu'un. `discriminator` = valeur de `presetValue.type` (le type
+ * estampillé au save qui distingue le sous-type), sinon la clé elle-même.
+ */
+export declare function listCostumFormNodes(data: CostumJsonData): Array<{
+    typeKey: string;
+    collection: string;
+    add: boolean;
+    createLabel: string | null;
+    discriminator?: string;
+}>;
+export declare function digestCostumJson(data: CostumJsonData, collection: Collection, meta: {
+    costumId: string;
+    costumType: string;
+    slug?: string;
+    baseFieldNames?: string[];
+}, opts?: {
+    typeKey?: string;
+}): DigestedCostum | null;
+export {};

package/types/costum/runtime-map.d.ts

@@ -1,3 +1,13 @@
-import type { Collection, CostumCollectionExt } from "./types.js";
-export type CostumRuntimeEntry = Pick<CostumCollectionExt, "schema" | "fields" | "presets" | "hidden">;
+import type { Collection, CostumCollectionExt, CostumExtensionField } from "./types.js";
+/** Variante runtime SYNC (subtype-aware) : sélectionnée par `discriminator` (= serverData.type). */
+export interface CostumRuntimeVariant {
+    discriminator: string | null;
+    schema: object;
+    fields: CostumExtensionField[];
+    presets: Record<string, unknown>;
+    hidden: string[];
+}
+export type CostumRuntimeEntry = Pick<CostumCollectionExt, "schema" | "fields" | "presets" | "hidden"> & {
+    variants?: CostumRuntimeVariant[];
+};
 export declare const COSTUM_RUNTIME: Record<string, Partial<Record<Collection, CostumRuntimeEntry>>>;

package/types/costum/runtime.d.ts

@@ -1,5 +1,23 @@
 import type { CostumExtensionModule, CostumExtensionField, KnownCostumSlug, Collection } from "./types.js";
 import type { BaseEntity } from "../api/BaseEntity.js";
+/**
+ * Invalide le cache costum live — d'UN slug (ex. après avoir modifié ce costum en base), ou de TOUT
+ * (`invalidateCostumCache()`). Le prochain accès refetchera `getcostumjson` (C2e). Sans effet sur le bundle.
+ */
+export declare function invalidateCostumCache(slug?: string): void;
+/**
+ * Énumère TOUS les formulaires costum d'un slug (UN descripteur PAR SOUS-TYPE = clé `typeObj`) via
+ * getcostumjson — pour l'assistant config (génération multi-form + routage `editModalMatch`). Distinct de
+ * `CostumScope.describeForm(collection)` qui n'en renvoie qu'UN par collection. Seuls les sous-types dont la
+ * collection de base est gérée par les fabriques (poi/organizations/projects/events) sont retournés.
+ */
+export declare function describeCostumForms(user: BaseEntity, slug: string): Promise<CostumFormDescriptor[]>;
+/**
+ * Pré-charge EN BATCH les costums (par slug) manquants/périmés du cache live, AVANT un revive synchrone
+ * (finalizer de `searchCostum`, `get()`, `entitySlug`). Dédup + TTL : un slug déjà frais est ignoré.
+ * Chaque fetch qui échoue est avalé (offline → le revive retombera sur le bundle). Concurrence bornée.
+ */
+export declare function prefetchCostums(user: BaseEntity, sourceKeys: (string | null | undefined)[]): Promise<void>;
 /**
  * Contexte costum résolu, attaché à une instance d'entité via `config.costumCtx`.
  * Porté tel quel par `BaseEntity._costumCtx` et consommé par les 3 couches de filtrage.
@@ -56,6 +74,10 @@ export interface CostumFormDescriptor {
      *  Le consommateur les exclut du formulaire (les champs costum portent aussi `hidden` par champ). */
     hidden: string[];
     fields: CostumFieldDescriptor[];
+    /** Clé `typeObj` (sous-type) d'où vient ce form — présent quand issu de `describeCostumForms` (énumération). */
+    typeKey?: string;
+    /** Valeur de `type` estampillée au save qui distingue le sous-type (= presetValue.type, sinon typeKey). */
+    discriminator?: string;
 }
 /**
  * Scope costum : fabrique des entités liées à un costum. Réutilise le `user` (parent, deps, auth)
@@ -68,8 +90,12 @@ export declare class CostumScope {
     private readonly costumId;
     private readonly costumType;
     constructor(user: BaseEntity, slug: KnownCostumSlug | (string & {}), module: CostumExtensionModule, costumId: string, costumType: string);
-    /** Construit le `CostumRuntimeContext` pour une collection donnée (null si le costum ne la couvre pas). */
-    contextFor(collection: Collection): CostumRuntimeContext | null;
+    /**
+     * Construit le `CostumRuntimeContext` pour une collection (null si non couverte). `type` (optionnel) = le
+     * sous-type voulu (= `presetValue.type` de la variante) : sélectionne l'overlay de CE sous-type, sinon la
+     * racine=union. Indispensable au CREATE d'un sous-type précis (bon `type`/presets/champs — cf. P0 write-safety).
+     */
+    contextFor(collection: Collection, type?: string | null): CostumRuntimeContext | null;
     /** Crée une entité de `collection` sous ce costum (presets appliqués, surchargeables par `data`). */
     private create;
     poi(data?: Record<string, unknown>): Promise<import("../index.js").Poi>;
@@ -85,20 +111,28 @@ export declare class CostumScope {
     describeForm(collection: Collection): CostumFormDescriptor | null;
 }
 /**
- * Dérive un `CostumRuntimeContext` SYNCHRONE depuis le `source.key` d'un élément CHARGÉ + sa collection
- * (inc2). Permet aux entités revifiées hors scope (`fromServerData` des résultats `searchCostum`,
- * `me.poi({id})`) de retrouver leurs champs costum (writable + dispatch) sans `me.costum(slug)`.
- * Utilise la map bundlée `COSTUM_RUNTIME` (sync) + `COSTUM_META`. Renvoie null si le costum/collection est
- * inconnu (costum hors registry → résolution live = inc2b).
+ * Dérive un `CostumRuntimeContext` SYNCHRONE depuis le `source.key` d'un élément CHARGÉ + sa collection.
+ * Permet aux entités revifiées (`fromServerData` des résultats `searchCostum`, `me.poi({id})`) de retrouver
+ * leurs champs costum (writable + dispatch) sans `me.costum(slug)`.
+ *
+ * **LIVE-FIRST** (RFC fil C / cadrage C2) : le cache live FRAIS prime (un costum modifié en base est reflété
+ * sans republier), sinon la map bundlée `COSTUM_RUNTIME` (warm-start / offline), sinon ctx nu / null. Le
+ * cache est peuplé par `prefetchCostums` (async, AVANT le revive) ou `me.costum`/`loadCostumScope`.
  */
-export declare function resolveCostumCtxFromSource(sourceKey: string | undefined | null, collection: Collection): CostumRuntimeContext | null;
+export declare function resolveCostumCtxFromSource(sourceKey: string | undefined | null, collection: Collection, type?: string | null): CostumRuntimeContext | null;
 /**
- * Ouvre un scope costum FIELDLESS depuis une entité DÉJÀ CHARGÉE (zéro fetch) : `costumSlug` = slug de
- * l'entité (= `source.key` posé par le backend), `costumId/costumType` = l'entité porteuse. Pendant runtime
- * exact de `_withCostumContext` (BaseEntity), pour la voie « entité tenue » (un site nu sans form). Le
- * backend re-gate `found` sur l'existence d'un costum sur l'entité → un site sans costum n'estampille rien.
+ * Ouvre un scope costum depuis une entité DÉJÀ CHARGÉE (org/projet/event porteur d'un costum) : `costumSlug`
+ * = slug de l'entité (= `source.key` posé par le backend), `costumId/costumType` = l'entité porteuse. C'est
+ * la voie AMBIANTE (« costum du déploiement ») de `me.costum(entity)`.
+ *
+ * Le scope porte les DÉFINITIONS du costum (champs + presets de sous-type, ex. `type:"article"`), PAS
+ * seulement l'identité : sinon un CREATE de sous-type sous l'ambiant perd le `type` forcé → rejet enum ADD_*.
+ * Résolution (dégradée, jamais throw) : 1) cache live frais (zéro fetch — le costum est déjà chargé au rendu
+ * du site) ; 2) digest live `getcostumjson` (comble presets/champs + peuple le cache) ; 3) fieldless
+ * (identité seule — site nu sans costum, ou offline = comportement historique). Le backend re-gate `found`
+ * sur l'existence d'un costum → un site sans costum n'estampille rien.
  */
-export declare function costumScopeFromEntity(user: BaseEntity, entity: BaseEntity): CostumScope;
+export declare function costumScopeFromEntity(user: BaseEntity, entity: BaseEntity): Promise<CostumScope>;
 /**
  * Résout un `CostumScope` par SLUG pour un user connecté.
  *  - slug à champs (meta + loader) → charge le module généré (code-split via dynamic import).
@@ -106,3 +140,10 @@ export declare function costumScopeFromEntity(user: BaseEntity, entity: BaseEnti
  *  - slug HORS registry → résolution LIVE via `slug/getinfo` (contextId/contextType) → scope nu (tier 3b).
  */
 export declare function resolveCostumScope(user: BaseEntity, slug: KnownCostumSlug | (string & {})): Promise<CostumScope>;
+/**
+ * Charge EN LIVE le scope costum d'un slug hors registre (getcostumjson) et pose le `CostumRuntimeContext`
+ * de la collection donnée sur l'entité — pour ÉDITER un élément d'un costum non bundlé avec ses champs
+ * (comble l'édition vide L4). Idempotent : ne refetch pas si le cache live couvre déjà (slug, collection).
+ * No-op si le costum ne résout pas / ne couvre pas la collection (l'entité reste en scope d'identité).
+ */
+export declare function loadCostumContext(user: BaseEntity, slug: string, collection: Collection): Promise<CostumRuntimeContext | null>;

package/types/costum/types.d.ts

@@ -11,6 +11,17 @@ export interface CostumExtensionField {
     enum?: string[];
     multiple?: boolean;
 }
+/** Sous-type (subtype-aware) d'une collection : overlay create/édition résolu par `discriminator` (= presetValue.type). */
+export interface CostumCollectionVariant {
+    typeKey: string;
+    discriminator: string | null;
+    add: boolean;
+    createLabel: string | null;
+    presets: Record<string, unknown>;
+    hidden: string[];
+    schema: object;
+    fields: CostumExtensionField[];
+}
 export interface CostumCollectionExt {
     schema: object;
     fields: CostumExtensionField[];
@@ -18,6 +29,8 @@ export interface CostumCollectionExt {
     hidden: string[];
     add: boolean;
     createLabel: string | null;
+    /** Sous-types : émis SSI >1 form/collection. La racine (schema/fields) reste l'UNION pour la LECTURE. */
+    variants?: CostumCollectionVariant[];
 }
 export interface CostumExtensionModule {
     slug: string;